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.45).
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.45).
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 * Search options:: Linking to a specific location
115 * Custom searches:: When the default search is not enough
116 * Remember:: Org-trees store quick notes
120 * Radio targets:: Make targets trigger links in plain text.
121 * CamelCase links:: Activating CamelCase words as links
125 * TODO basics:: Marking and displaying TODO entries
126 * TODO extensions:: Workflow and assignments
127 * Priorities:: Some things are more important than others
128 * Breaking down tasks:: Splitting a task into managable pieces
129 * Checkboxes:: Tick-off lists
131 Extended use of TODO keywords
133 * Workflow states:: From TODO to DONE in steps
134 * TODO types:: I do this, Fred the rest
135 * Per file keywords:: Different files, different requirements
139 * Time stamps:: Assigning a time to a tree entry
140 * Creating timestamps:: Commands which insert timestamps
141 * Progress logging:: Documenting when what work was done.
145 * Closing items:: When was this entry marked DONE?
146 * Clocking work time:: When exactly did you work on this item?
150 * Tag inheritance:: Tags use the tree structure of the outline
151 * Setting tags:: How to assign tags to a headline
152 * Tag searches:: Searching for combinations of tags
156 * Agenda files:: Files being searched for agenda information
157 * Agenda dispatcher:: Keyboard access to agenda views
158 * Weekly/Daily agenda:: The calendar page with current tasks
159 * Global TODO list:: All unfinished action items
160 * Matching headline tags:: Structured information with fine-tuned search
161 * Timeline:: Time-sorted view for single file
162 * Agenda commands:: Remote editing of org trees
164 The weekly/daily agenda
166 * Categories:: Not all tasks are equal
167 * Time-of-day specifications:: How the agenda knows the time
168 * Calendar/Diary integration:: Integrating Anniversaries and more
169 * Sorting of agenda items:: The order of things
173 * Math symbols:: TeX macros for symbols and Greek letters
174 * Subscripts and Superscripts:: Simple syntax for raising/lowering text
175 * LaTeX fragments:: Complex formulas made easy
176 * Processing LaTeX fragments:: Previewing LaTeX processing
177 * CDLaTeX mode:: Speed up entering of formulas
181 * ASCII export:: Exporting to plain ASCII
182 * HTML export:: Exporting to HTML
183 * XOXO export:: Exporting to XOXO
184 * iCalendar export:: Exporting in iCalendar format
185 * Text interpretation:: How the exporter looks at the file
187 Text interpretation by the exporter
189 * Comment lines:: Some lines will not be exported
190 * Enhancing text:: Subscripts, symbols and more
191 * Export options:: How to influence the export settings
195 * Configuration:: Defining projects
196 * Sample configuration:: Example projects
197 * Triggering publication:: Publication commands
201 * Project alist:: The central configuration variable
202 * Sources and destinations:: From here to there
203 * Selecting files:: What files are part of the project?
204 * Publishing action:: Setting the function doing the publishing
205 * Publishing options:: Tweaking HTML export
206 * Publishing links:: Which links keep working after publishing?
207 * Project page index:: Publishing a list of project files
211 * Simple example:: One-component publishing
212 * Complex example:: A multi-component publishing example
216 * Completion:: M-TAB knows what you need
217 * Customization:: Adapting Org-mode to your taste
218 * In-buffer settings:: Overview of the #+KEYWORDS
219 * The very busy C-c C-c key:: When in doubt, press C-c C-c
220 * Clean view:: Getting rid of leading stars in the outline
221 * TTY keys:: Using Org-mode on a tty
222 * Interaction:: Other Emacs packages
223 * Bugs:: Things which do not work perfectly
225 Interaction with other packages
227 * Cooperation:: Packages Org-mode cooperates with
228 * Conflicts:: Packages that lead to conflicts
230 Extensions, Hooks and Hacking
232 * Extensions:: Existing 3rd-part extensions
233 * Dynamic blocks:: Automatically filled blocks
236 File: org, Node: Introduction, Next: Document structure, Prev: Top, Up: Top
243 * Summary:: Brief summary of what Org-mode does
244 * Installation:: How to install a downloaded version of Org-mode
245 * Activation:: How to activate Org-mode for certain buffers.
246 * Feedback:: Bug reports, ideas, patches etc.
249 File: org, Node: Summary, Next: Installation, Prev: Introduction, Up: Introduction
254 Org-mode is a mode for keeping notes, maintaining ToDo lists, and doing
255 project planning with a fast and effective plain-text system.
257 Org-mode develops organizational tasks around NOTES files that
258 contain information about projects as plain text. Org-mode is
259 implemented on top of outline-mode, which makes it possible to keep the
260 content of large files well structured. Visibility cycling and
261 structure editing help to work with the tree. Tables are easily
262 created with a built-in table editor. Org-mode supports ToDo items,
263 deadlines, time stamps, and scheduling. It dynamically compiles
264 entries into an agenda that utilizes and smoothly integrates much of
265 the Emacs calendar and diary. Plain text URL-like links connect to
266 websites, emails, Usenet messages, BBDB entries, and any files related
267 to the projects. For printing and sharing of notes, an Org-mode file
268 can be exported as a structured ASCII file, as HTML, or (todo and
269 agenda items only) as an iCalendar file. It can also serve as a
270 publishing tool for a set of linked webpages.
272 Org-mode keeps simple things simple. When first fired up, it should
273 feel like a straightforward, easy to use outliner. Complexity is not
274 imposed, but a large amount of functionality is available when you need
275 it. Org-mode can be used on different levels and in different ways, for
278 * as an outline extension with visibility cycling and structure editing
279 * as an ASCII system and table editor for taking structured notes
280 * as an ASCII table editor with spreadsheet-like capabilities
281 * as a TODO list editor
282 * as a full agenda and planner with deadlines and work scheduling
283 * as a simple hypertext system, with HTML export
284 * as a publishing tool to create a set of interlinked webpages
286 The Org-mode table editor can be integrated into any major mode by
287 activating the minor Orgtbl-mode.
289 There is a website for Org-mode which provides links to the newest
290 version of Org-mode, as well as additional information, frequently asked
291 questions (FAQ), links to tutorials etc. This page is located at
292 `http://www.astro.uva.nl/~dominik/Tools/org/'.
295 File: org, Node: Installation, Next: Activation, Prev: Summary, Up: Introduction
300 Important: If Org-mode is part of the Emacs distribution or an XEmacs
301 package, please skip this section and go directly to *Note Activation::.
303 If you have downloaded Org-mode from the Web, you must take the
304 following steps to install it: Go into the Org-mode distribution
305 directory and edit the top section of the file `Makefile'. You must
306 set the name of the Emacs binary (likely either `emacs' or `xemacs'),
307 and the paths to the directories where local Lisp and Info files are
308 kept. If you don't have access to the system-wide directories, create
309 your own two directories for these files, enter them into the Makefile,
310 and make sure Emacs finds the Lisp files by adding the following line
313 (setq load-path (cons "~/path/to/lispdir" load-path))
315 XEmacs users now need to install the file `noutline.el' from the
316 `xemacs' subdirectory of the Org-mode distribution. Use the command:
318 make install-noutline
320 Now byte-compile and install the Lisp files with the shell commands:
325 If you want to install the info documentation, use this command:
329 Then add to `.emacs':
331 ;; This line only if org-mode is not part of the X/Emacs distribution.
332 (require 'org-install)
335 File: org, Node: Activation, Next: Feedback, Prev: Installation, Up: Introduction
340 Add the following lines to your `.emacs' file. The last two lines
341 define _global_ keys for the commands `org-store-link' and `org-agenda'
342 - please choose suitable keys yourself.
344 ;; The following lines are always needed. Choose your own keys.
345 (add-to-list 'auto-mode-alist '("\\.org$" . org-mode))
346 (define-key global-map "\C-cl" 'org-store-link)
347 (define-key global-map "\C-ca" 'org-agenda)
349 Furthermore, you must activate `font-lock-mode' in org-mode buffers,
350 because significant functionality depends on font-locking being active.
351 You can do this with either one of the following two lines (XEmacs
352 user must use the second option):
353 (global-font-lock-mode 1) ; for all buffers
354 (add-hook 'org-mode-hook 'turn-on-font-lock) ; org-mode buffers only
356 With this setup, all files with extension `.org' will be put into
357 Org-mode. As an alternative, make the first line of a file look like
360 MY PROJECTS -*- mode: org; -*-
362 which will select Org-mode for this buffer no matter what the file's
363 name is. See also the variable `org-insert-mode-line-in-empty-file'.
366 File: org, Node: Feedback, Prev: Activation, Up: Introduction
371 If you find problems with Org-mode, or if you have questions, remarks,
372 or ideas about it, please contact the maintainer Carsten Dominik at
373 <dominik@science.uva.nl>.
375 For bug reports, please provide as much information as possible,
376 including the version information of Emacs (`C-h v emacs-version
377 <RET>') and Org-mode (`C-h v org-version <RET>'), as well as the
378 Org-mode related setup in `.emacs'. If an error occurs, a traceback
379 can be very useful. Often a small example file helps, along with clear
382 1. What exactly did you do?
384 2. What did you expect to happen?
386 3. What happened instead?
387 Thank you for helping to improve this mode.
390 File: org, Node: Document structure, Next: Tables, Prev: Introduction, Up: Top
395 Org-mode is based on outline mode and provides flexible commands to
396 edit the structure of the document.
400 * Outlines:: Org-mode is based on outline-mode
401 * Headlines:: How to typeset org-tree headlines
402 * Visibility cycling:: Show and hide, much simplified
403 * Motion:: Jumping to other headlines
404 * Structure editing:: Changing sequence and level of headlines
405 * Archiving:: Move done task trees to a different place
406 * Sparse trees:: Matches embedded in context
407 * Plain lists:: Additional structure within an entry
410 File: org, Node: Outlines, Next: Headlines, Prev: Document structure, Up: Document structure
415 Org-mode is implemented on top of outline-mode. Outlines allow to
416 organize a document in a hierarchical structure, which (at least for
417 me) is the best representation of notes and thoughts. Overview over
418 this structure is achieved by folding (hiding) large parts of the
419 document to show only the general document structure and the parts
420 currently being worked on. Org-mode greatly simplifies the use of
421 outlines by compressing the entire show/hide functionality into a
422 single command `org-cycle', which is bound to the <TAB> key.
425 File: org, Node: Headlines, Next: Visibility cycling, Prev: Outlines, Up: Document structure
430 Headlines define the structure of an outline tree. The headlines in
431 Org-mode start with one or more stars, on the left margin. For example:
439 * Another top level headline
441 Some people find the many stars too noisy and would prefer an outline
442 that has whitespace followed by a single star as headline starters.
443 *Note Clean view:: describes a setup to realize this.
446 File: org, Node: Visibility cycling, Next: Motion, Prev: Headlines, Up: Document structure
448 2.3 Visibility cycling
449 ======================
451 Outlines make it possible to hide parts of the text in the buffer.
452 Org-mode uses just two commands, bound to <TAB> and `S-<TAB>' to change
453 the visibility in the buffer.
456 _Subtree cycling_: Rotate current subtree between the states
458 ,-> FOLDED -> CHILDREN -> SUBTREE --.
459 '-----------------------------------'
461 The cursor must be on a headline for this to work(1). When the
462 cursor is at the beginning of the buffer and the first line is not
463 a headline, then <TAB> actually runs global cycling (see
464 below)(2). Also when called with a prefix argument (`C-u <TAB>'),
465 global cycling is invoked.
469 _Global cycling_: Rotate the entire buffer between the states
471 ,-> OVERVIEW -> CONTENTS -> SHOW ALL --.
472 '--------------------------------------'
474 Note that inside tables, `S-<TAB>' jumps to the previous field.
479 When Emacs first visits an Org-mode file, the global state is set to
480 OVERVIEW, i.e. only the top level headlines are visible. This can be
481 configured through the variable `org-startup-folded', or on a per-file
482 basis by adding one of the following lines anywhere in the buffer:
488 ---------- Footnotes ----------
490 (1) see, however, the option `org-cycle-emulate-tab'.
492 (2) see the option `org-cycle-global-at-bob'.
495 File: org, Node: Motion, Next: Structure editing, Prev: Visibility cycling, Up: Document structure
500 The following commands jump to other headlines in the buffer.
509 Next heading same level.
512 Previous heading same level.
515 Backward to higher level heading.
518 Jump to a different place without changing the current outline
519 visibility. Shows the document structure in a temporary buffer,
520 where you can use visibility cycling (<TAB>) to find your
521 destination. After pressing <RET>, the cursor moves to the
522 selected location in the original buffer, and the headings
523 hierarchy above it is made visible.
526 File: org, Node: Structure editing, Next: Archiving, Prev: Motion, Up: Document structure
528 2.5 Structure editing
529 =====================
532 Insert new heading with same level as current. If the cursor is
533 in a plain list item, a new item is created (*note Plain lists::).
534 To force creation of a new headline, use a prefix arg, or first
535 press <RET> to get to the beginning of the next line. When this
536 command is used in the middle of a line, the line is split and the
537 rest of the line becomes the new headline. If the command is used
538 at the beginning of a headline, the new headline is created before
539 the current line. If at the beginning of any other line, the
540 content of that line is made the new heading.
543 Insert new TODO entry with same level as current heading.
546 Promote current heading by one level.
549 Demote current heading by one level.
552 Promote the current subtree by one level.
555 Demote the current subtree by one level.
558 Move subtree up (swap with previous subtree of same level).
561 Move subtree down (swap with next subtree of same level).
565 Kill subtree, i.e. remove it from buffer but save in kill ring.
568 Copy subtree to kill ring.
571 Yank subtree from kill ring. This does modify the level of the
572 subtree to make sure the tree fits in nicely at the yank position.
573 The yank level can also be specified with a prefix arg, or by
574 yanking after a headline marker like `****'.
576 When there is an active region (transient-mark-mode), promotion and
577 demotion work on all headlines in the region. To select a region of
578 headlines, it is best to place both point and mark at the beginning of a
579 line, mark at the beginning of the first headline, and point at the line
580 just after the last headline to change. Note that when the cursor is
581 inside a table (*note Tables::), the Meta-Cursor keys have different
585 File: org, Node: Archiving, Next: Sparse trees, Prev: Structure editing, Up: Document structure
590 When a project represented by a (sub)tree is finished, you may want to
591 move the tree out of the way and to stop it from contributing to the
592 agenda. Org-mode knows two ways of archiving. You can mark a tree with
593 the ARCHIVE tag, or you can move an entire (sub)tree to a different
598 * ARCHIVE tag:: Marking a tree as inactive
599 * Moving subtrees:: Moving a tree to an archive file
602 File: org, Node: ARCHIVE tag, Next: Moving subtrees, Prev: Archiving, Up: Archiving
604 2.6.1 The ARCHIVE tag
605 ---------------------
607 A headline that is marked with the ARCHIVE tag (*note Tags::) stays at
608 its location in the outline tree, but behaves in the following way:
609 - It does not open when you attempt to do so with a visibility
610 cycling command (*note Visibility cycling::). You can force
611 cycling archived subtrees with `C-<TAB>', or by setting the option
612 `org-cycle-open-archived-trees'. Also normal outline commands like
613 `show-all' will open archived subtrees.
615 - During sparse tree construction (*note Sparse trees::), matches in
616 archived subtrees are not exposed, unless you configure the option
617 `org-sparse-tree-open-archived-trees'.
619 - During agenda view construction (*note Agenda views::), the
620 content of archived trees is ignored unless you configure the
621 option `org-agenda-skip-archived-trees'.
623 - Archived trees are not exported (*note Exporting::), only the
624 headline is. Configure the details using the variable
625 `org-export-with-archived-trees'.
627 The following commands help managing the ARCHIVE tag:
630 Toggle the ARCHIVE tag for the current headline. When the tag is
631 set, the headline changes to a shadowish face, and the subtree
635 Check if any direct children of the current headline should be
636 archived. To do this, each subtree is checked for open TODO
637 entries. If none are found, the command offers to set the ARCHIVE
638 tag for the child. If the cursor is _not_ on a headline when this
639 command is invoked, the level 1 trees will be checked.
642 Cycle a tree even if it is tagged with ARCHIVE.
645 File: org, Node: Moving subtrees, Prev: ARCHIVE tag, Up: Archiving
647 2.6.2 Moving subtrees
648 ---------------------
650 Once an entire project is finished, you may want to move it to a
651 different location, either in the current file, or even in a different
652 file, the archive file.
655 Archive the subtree starting at the cursor position to the location
656 given by `org-archive-location'.
659 Check if any direct children of the current headline could be
660 moved to the archive. To do this, each subtree is checked for
661 open TODO entries. If none are found, the command offers to move
662 it to the archive location. If the cursor is _not_ on a headline
663 when this command is invoked, the level 1 trees will be checked.
665 The default archive location is a file in the same directory as the
666 current file, with the name derived by appending `_archive' to the
667 current file name. For information and examples on how to change this,
668 see the documentation string of the variable `org-archive-location'.
671 File: org, Node: Sparse trees, Next: Plain lists, Prev: Archiving, Up: Document structure
676 An important feature of Org-mode is the ability to construct _sparse
677 trees_ for selected information in an outline tree. A sparse tree
678 means that the entire document is folded as much as possible, but the
679 selected information is made visible along with the headline structure
680 above it(1). Just try it out and you will see immediately how it works.
682 Org-mode contains several commands creating such trees. The most
683 basic one is `org-occur':
686 Occur. Prompts for a regexp and shows a sparse tree with all
687 matches. If the match is in a headline, the headline is made
688 visible. If the match is in the body of an entry, headline and
689 body are made visible. In order to provide minimal context, also
690 the full hierarchy of headlines above the match is shown, as well
691 as the headline following the match. Each match is also
692 highlighted; the highlights disappear when the buffer is changed
693 with an editing command.
694 For frequently used sparse trees of specific search strings, you can
695 use the variable `org-agenda-custom-commands' to define fast keyboard
696 access to specific sparse trees. These commands will then be
697 accessible through the agenda dispatcher (*note Agenda dispatcher::).
700 (setq org-agenda-custom-commands
701 '(("f" occur-tree "FIXME")))
703 will define the key `C-c a f' as a shortcut for creating a sparse tree
704 matching the string `FIXME'.
706 Other commands use sparse trees as well. For example `C-c C-v'
707 creates a sparse TODO tree (*note TODO basics::).
709 To print a sparse tree, you can use the Emacs command
710 `ps-print-buffer-with-faces' which does not print invisible parts of
711 the document (2). Or you can use the command `C-c C-e v' to export
712 only the visible part of the document and print the resulting file.
714 ---------- Footnotes ----------
716 (1) See also the variables `org-show-hierarchy-above' and
717 `org-show-following-heading'.
719 (2) This does not work under XEmacs, because XEmacs uses selective
720 display for outlining, not text properties.
723 File: org, Node: Plain lists, Prev: Sparse trees, Up: Document structure
728 Within an entry of the outline tree, hand-formatted lists can provide
729 additional structure. They also provide a way to create lists of
730 checkboxes (*note Checkboxes::). Org-mode supports editing such lists,
731 and the HTML exporter (*note Exporting::) does parse and format them.
733 Org-mode knows ordered and unordered lists. Unordered list items
734 start with `-', `+', or `*'(1) as bullets. Ordered list items start
735 with `1.' or `1)'. Items belonging to the same list must have the same
736 indentation on the first line. In particular, if an ordered list
737 reaches number `10.', then the 2-digit numbers must be written
738 left-aligned with the other numbers in the list. Indentation also
739 determines the end of a list item. It ends before the next line that
740 is indented like the bullet/number, or less. For example:
743 My favorite scenes are (in this order)
744 1. The attack of the Rohirrim
745 2. Eowyns fight with the witch king
746 + this was already my favorite scene in the book
747 + I really like Miranda Otto.
748 3. Peter Jackson being shot by Legolas
750 He makes a really funny face when it happens.
751 But in the end, not individual scenes matter but the film as a whole.
753 Org-mode supports these lists by tuning filling and wrapping
754 commands to deal with them correctly(2).
756 The following commands act on items when the cursor is in the first
757 line of an item (the line with the bullet or number).
760 Items can be folded just like headline levels if you set the
761 variable `org-cycle-include-plain-lists'. The level of an item is
762 then given by the indentation of the bullet/number. Items are
763 always subordinate to real headlines, however; the hierarchies
764 remain completely separated.
767 Insert new item at current level. With prefix arg, force a new
768 heading (*note Structure editing::). If this command is used in
769 the middle of a line, the line is _split_ and the rest of the line
770 becomes the new item. If this command is executed in the
771 _whitespace before a bullet or number_, the new item is created
772 _before_ the current item. If the command is executed in the
773 white space before the text that is part of an item but does not
774 contain the bullet, a bullet is added to the current line.
777 Insert a new item with a checkbox (*note Checkboxes::).
781 Jump to the previous/next item in the current list.
785 Move the item including subitems up/down (swap with previous/next
786 item of same indentation). If the list is ordered, renumbering is
791 Decrease/increase the indentation of the item, including subitems.
792 Initially, the item tree is selected based on current indentation.
793 When these commands are executed several times in direct
794 succession, the initially selected region is used, even if the new
795 indentation would imply a different hierarchy. To use the new
796 hierarchy, break the command chain with a cursor motion or so.
799 If there is a checkbox (*note Checkboxes::) in the item line,
800 toggle the state of the checkbox. Otherwise, if this is an
801 ordered list, renumber the ordered list at the cursor.
803 ---------- Footnotes ----------
805 (1) When using `*' as a bullet, lines must be indented or they will
806 be seen as top-level headlines. Also, when you are hiding leading
807 stars to get a clean outline view, plain list items starting with a
808 star are visually indistinguishable from true headlines. In short:
809 even though `*' is supported, it may be better not to use it for plain
812 (2) Org-mode only changes the filling settings for Emacs. For
813 XEmacs, you should use Kyle E. Jones' `filladapt.el'. To turn is on,
818 File: org, Node: Tables, Next: Hyperlinks, Prev: Document structure, Up: Top
823 Org-mode has a very fast and intuitive table editor built-in.
824 Spreadsheet-like calculations are supported in connection with the
825 Emacs `calc' package.
829 * Built-in table editor:: Simple tables
830 * Narrow columns:: Stop wasting space in tables
831 * Table calculations:: Compute a field from other fields
832 * orgtbl-mode:: The table editor as minor mode
833 * table.el:: Complex tables
836 File: org, Node: Built-in table editor, Next: Narrow columns, Prev: Tables, Up: Tables
838 3.1 The built-in table editor
839 =============================
841 Org-mode makes it easy to format tables in plain ASCII. Any line with
842 `|' as the first non-white character is considered part of a table.
843 `|' is also the column separator. A table might look like this:
845 | Name | Phone | Age |
846 |-------+-------+-----|
847 | Peter | 1234 | 17 |
850 A table is re-aligned automatically each time you press <TAB> or
851 <RET> or `C-c C-c' inside the table. <TAB> also moves to the next
852 field (<RET> to the next row) and creates new table rows at the end of
853 the table or before horizontal lines. The indentation of the table is
854 set by the first line. Any line starting with `|-' is considered as a
855 horizontal separator line and will be expanded on the next re-align to
856 span the whole table width. So, to create the above table, you would
862 and then press <TAB> to align the table and start filling in fields.
864 When typing text into a field, Org-mode treats <DEL>, <Backspace>,
865 and all character keys in a special way, so that inserting and deleting
866 avoids shifting other fields. Also, when typing _immediately after the
867 cursor was moved into a new field with `<TAB>', `S-<TAB>' or `<RET>'_,
868 the field is automatically made blank. If this behavior is too
869 unpredictable for you, configure the variables
870 `org-enable-table-editor' and `org-table-auto-blank-field'.
872 Creation and conversion
873 .......................
876 Convert the active region to table. If every line contains at
877 least one TAB character, the function assumes that the material is
878 tab separated. If not, lines are split at whitespace into fields.
879 You can use a prefix argument to indicate the minimum number of
880 consecutive spaces required to identify a field separator
882 If there is no active region, this command creates an empty
883 Org-mode table. But it's easier just to start typing, like
884 `|Name|Phone|Age <RET> |- <TAB>'.
886 Re-aligning and field motion
887 ............................
890 Re-align the table without moving the cursor.
893 Re-align the table, move to the next field. Creates a new row if
897 Re-align, move to previous field.
900 Re-align the table and move down to next row. Creates a new row if
901 necessary. At the beginning or end of a line, <RET> still does
902 NEWLINE, so it can be used to split a table.
904 Column and row editing
905 ......................
909 Move the current column left/right.
912 Kill the current column.
915 Insert a new column to the left of the cursor position.
919 Move the current row up/down.
922 Kill the current row or horizontal line.
925 Insert a new row above (with arg: below) the current row.
928 Insert a horizontal line below current row. With prefix arg, the
929 line is created above the current line.
932 Sort the table lines in the region. Point and mark must be in the
933 first and last line to be included, and must be in the column that
934 should be used for sorting. The command prompts for numerical
935 versus alphanumerical sorting.
941 Copy a rectangular region from a table to a special clipboard.
942 Point and mark determine edge fields of the rectangle. The
943 process ignores horizontal separator lines.
946 Copy a rectangular region from a table to a special clipboard, and
947 blank all fields in the rectangle. So this is the "cut" operation.
950 Paste a rectangular region into a table. The upper right corner
951 ends up in the current field. All involved fields will be
952 overwritten. If the rectangle does not fit into the present table,
953 the table is enlarged as needed. The process ignores horizontal
957 Wrap several fields in a column like a paragraph. If there is an
958 active region, and both point and mark are in the same column, the
959 text in the column is wrapped to minimum width for the given
960 number of lines. A prefix ARG may be used to change the number of
961 desired lines. If there is no region, the current field is split
962 at the cursor position and the text fragment to the right of the
963 cursor is prepended to the field one line down. If there is no
964 region, but you specify a prefix ARG, the current field is made
965 blank, and the content is appended to the field above.
971 Install a new formula for the current column and replace current
972 field with the result of the formula.
975 Install a new formula for the current field, which must be a named
976 field. Evaluate the formula and replace the field content with the
980 Edit all formulas associated with the current table in a separate
984 Recalculate the current row by applying the stored formulas from
985 left to right. When called with a `C-u' prefix, recalculate the
986 entire table, starting with the first non-header line (i.e. below
987 the first horizontal separator line). For details, see *Note
988 Table calculations::.
991 Rotate the calculation mark in first column through the states `',
992 `#', `*', `!', `$'. For the meaning of these marks see *Note
993 Advanced features::. When there is an active region, change all
997 Which table column is the cursor in? Displays number >0 in echo
1001 Sum the numbers in the current column, or in the rectangle defined
1002 by the active region. The result is shown in the echo area and can
1003 be inserted with `C-y'.
1006 When current field is empty, copy from first non-empty field above.
1007 When not empty, copy current field down to next row and move cursor
1008 along with it. Depending on the variable
1009 `org-table-copy-increment', integer field values will be
1010 incremented during copy. This key is also used by CUA-mode (*note
1017 Edit the current field in a separate window. This is useful for
1018 fields that are not fully visible (*note Narrow columns::). When
1019 called with a `C-u' prefix, just make the full field visible, so
1020 that it can be edited in place.
1023 This is an alias for `C-u C-c `' to make the current field fully
1026 `M-x org-table-import'
1027 Import a file as a table. The table should be TAB- or whitespace
1028 separated. Useful, for example, to import an Excel table or data
1029 from a database, because these programs generally can write
1030 TAB-separated text files. This command works by inserting the
1031 file into the buffer and then converting the region to a table.
1032 Any prefix argument is passed on to the converter, which uses it
1033 to determine the separator.
1035 `M-x org-table-export'
1036 Export the table as a TAB-separated file. Useful for data
1037 exchange with, for example, Excel or database programs.
1040 If you don't like the automatic table editor because it gets in your
1041 way on lines which you would like to start with `|', you can turn it
1044 (setq org-enable-table-editor nil)
1046 Then the only table command that still works is `C-c C-c' to do a
1050 File: org, Node: Narrow columns, Next: Table calculations, Prev: Built-in table editor, Up: Tables
1055 The width of columns is automatically determined by the table editor.
1056 Sometimes a single field or a few fields need to carry more text,
1057 leading to inconveniently wide columns. To limit(1) the width of a
1058 column, one field anywhere in the column may contain just the string
1059 `<N>' where `N' is an integer specifying the width of the column in
1060 characters. The next re-align will then set the width of this column
1061 to no more than this value.
1063 |---+------------------------------| |---+--------|
1065 | 1 | one | | 1 | one |
1066 | 2 | two | ----\ | 2 | two |
1067 | 3 | This is a long chunk of text | ----/ | 3 | This=> |
1068 | 4 | four | | 4 | four |
1069 |---+------------------------------| |---+--------|
1071 Fields that are wider become clipped and end in the string `=>'. Note
1072 that the full text is still in the buffer, it is only invisible. To
1073 see the full text, hold the mouse over the field - a tooltip window
1074 will show the full content. To edit such a field, use the command `C-c
1075 `' (that is `C-c' followed by the backquote). This will open a new
1076 window with the full field. Edit it and finish with `C-c C-c'.
1078 When visiting a file containing a table with narrowed columns, the
1079 necessary character hiding has not yet happened, and the table needs to
1080 be aligned before it looks nice. Setting the option
1081 `org-startup-align-all-tables' will realign all tables in a file upon
1082 visiting, but also slow down startup. You can also set this option on
1083 a per-file basis with:
1088 ---------- Footnotes ----------
1090 (1) This feature does not work on XEmacs.
1093 File: org, Node: Table calculations, Next: orgtbl-mode, Prev: Narrow columns, Up: Tables
1095 3.3 Calculations in tables
1096 ==========================
1098 The table editor makes use of the Emacs `calc' package to implement
1099 spreadsheet-like capabilities. It can also evaluate Emacs Lisp forms to
1100 derive fields from other fields. Org-mode has two levels of complexity
1101 for table calculations. On the basic level, tables do only horizontal
1102 computations, so a field can be computed from other fields _in the same
1103 row_, and Org-mode assumes that there is only one formula for each
1104 column. This is very efficient to work with and enough for many tasks.
1105 On the complex level, columns and individual fields can be named for
1106 easier referencing in formulas, individual named fields can have their
1107 own formula associated with them, and recalculation can be automated.
1111 * Formula syntax:: How to write a formula
1112 * Lisp formulas:: An alternative way to write formulas
1113 * Column formulas:: Formulas valid for all fields in a column
1114 * Advanced features:: Field names, parameters and automatic recalc
1115 * Named-field formulas:: Formulas valid in single fields
1116 * Editing/debugging formulas:: Changing a stored formula
1117 * Appetizer:: Taste the power of calc
1120 File: org, Node: Formula syntax, Next: Lisp formulas, Prev: Table calculations, Up: Table calculations
1122 3.3.1 Formula syntax
1123 --------------------
1125 A formula can be any algebraic expression understood by the Emacs
1126 `calc' package. Note that `calc' has the slightly non-standard
1127 convention that `/' has lower precedence than `*', so that `a/b*c' is
1128 interpreted as `a/(b*c)'. Before evaluation by `calc-eval' (*note
1129 calc-eval: (calc)Calling Calc from Your Programs.), variable
1130 substitution takes place:
1132 $ refers to the current field
1133 $3 refers to the field in column 3 of the current row
1134 $3..$7 a vector of the fields in columns 3-7 of current row
1135 $P1..$P3 vector of column range, using column names
1136 &2 second data field above the current, in same column
1137 &5-2 vector from fifth to second field above current
1138 &III-II vector of fields between 2nd and 3rd hline above
1139 &III vector of fields between third hline above and current field
1140 $name a named field, parameter or constant
1142 The range vectors can be directly fed into the calc vector functions
1143 like `vmean' and `vsum'.
1145 `$name' is interpreted as the name of a column, parameter or
1146 constant. Constants are defined globally through the variable
1147 `org-table-formula-constants'. If you have the `constants.el' package,
1148 it will also be used to resolve constants, including natural constants
1149 like `$h' for Planck's constant, and units like `$km' for kilometers.
1150 Column names and parameters can be specified in special table lines.
1151 These are described below, see *Note Advanced features::.
1153 A formula can contain an optional mode string after a semicolon.
1154 This string consists of flags to influence calc's modes(1) during
1155 execution, e.g. `p20' to switch the internal precision to 20 digits,
1156 `n3', `s3', `e2' or `f4' to switch to normal, scientific, engineering,
1157 or fixed display format, respectively, and `D', `R', `F', and `S' to
1158 turn on degrees, radians, fraction and symbolic modes, respectively.
1159 In addition, you may provide a `printf' format specifier to reformat
1160 the final result. A few examples:
1162 $1+$2 Sum of first and second field
1163 $1+$2;%.2f Same, format result to two decimals
1164 exp($2)+exp($1) Math functions can be used
1165 $;%.1f Reformat current cell to 1 decimal
1166 ($3-32)*5/9 Degrees F -> C conversion
1167 $c/$1/$cm Hz -> cm conversion, using `constants.el'
1168 tan($1);Dp3s1 Compute in degrees, precision 3, display SCI 1
1169 sin($1);Dp3%.1e Same, but use printf specifier for display
1170 vmean($2..$7) Compute column range mean, using vector function
1171 vsum(&III) Sum numbers from 3rd hline above, up to here
1172 taylor($3,x=7,2) taylor series of $3, at x=7, second degree
1174 ---------- Footnotes ----------
1176 (1) By default, Org-mode uses the standard calc modes (precision 12,
1177 angular units degrees, fraction and symbolic modes off). The display
1178 format, however, has been changed to `(float 5)' to keep tables compact.
1179 The default settings can be configured using the variable
1180 `org-calc-default-modes'.
1183 File: org, Node: Lisp formulas, Next: Column formulas, Prev: Formula syntax, Up: Table calculations
1185 3.3.2 Emacs Lisp forms as formulas
1186 ----------------------------------
1188 It is also possible to write a formula in Emacs lisp; this can be useful
1189 for string manipulation and control structures. If a formula starts
1190 with a single quote followed by an opening parenthesis, then it is
1191 evaluated as a lisp form. The evaluation should return either a string
1192 or a number. Just as with `calc' formulas, you can provide a format
1193 specifier after a semicolon. A few examples:
1195 swap the first two characters of the content of column 1
1196 '(concat (substring "$1" 1 2) (substring "$1" 0 1) (substring "$1" 2))
1197 Add columns 1 and 2, equivalent to the calc's `$1+$2'
1201 File: org, Node: Column formulas, Next: Advanced features, Prev: Lisp formulas, Up: Table calculations
1203 3.3.3 Column formulas
1204 ---------------------
1206 To apply a formula to a field, type it directly into the field,
1207 preceded by an equal sign, like `=$1+$2'. When you press <TAB> or
1208 <RET> or `C-c C-c' with the cursor still in the field, the formula will
1209 be stored as the formula for the current column, evaluated and the
1210 current field replaced with the result. If the field contains only
1211 `=', the previously stored formula for this column is used.
1213 For each column, Org-mode will remember the most recently used
1214 formula. The information is stored in a special line starting with
1215 `#+TBLFM' directly below the table. When adding/deleting/moving
1216 columns with the appropriate commands, the stored equations will be
1217 modified accordingly. When a column used in a calculation is removed,
1218 references to this column become invalid and will cause an error upon
1219 applying the equation.
1221 Instead of typing an equation into the field, you may also use the
1222 command `C-c ='. It prompts for a formula (with default taken from the
1223 `#+TBLFM:' line) and applies it to the current field. A numerical
1224 prefix (e.g. `C-5 C-c =') will apply it to that many consecutive fields
1225 in the current column.
1227 To recompute all the fields in a line, use the command `C-c *'. It
1228 re-applies all stored equations to the current row, from left to right.
1229 With a `C-u' prefix, this will be done to every line in the table, so
1230 use this command it you want to make sure the entire table is
1231 up-to-date. `C-u C-c C-c' is another way to update the entire table.
1232 Global updating does not touch the line(s) above the first horizontal
1233 separator line, assuming that this is the table header.
1236 File: org, Node: Advanced features, Next: Named-field formulas, Prev: Column formulas, Up: Table calculations
1238 3.3.4 Advanced features
1239 -----------------------
1241 If you want the recalculation of fields to happen automatically, or if
1242 you want to be able to assign a formula to an individual field (instead
1243 of an entire column) you need to reserve the first column of the table
1244 for special marking characters. Here is an example of a table that
1245 collects exam results of students and makes use of these features:
1247 |---+---------+--------+--------+--------+-------+------|
1248 | | Student | Prob 1 | Prob 2 | Prob 3 | Total | Note |
1249 |---+---------+--------+--------+--------+-------+------|
1250 | ! | | P1 | P2 | P3 | Tot | |
1251 | # | Maximum | 10 | 15 | 25 | 50 | 10.0 |
1252 | ^ | | m1 | m2 | m3 | mt | |
1253 |---+---------+--------+--------+--------+-------+------|
1254 | # | Peter | 10 | 8 | 23 | 41 | 8.2 |
1255 | # | Sara | 6 | 14 | 19 | 39 | 7.8 |
1256 | # | Sam | 2 | 4 | 3 | 9 | 1.8 |
1257 |---+---------+--------+--------+--------+-------+------|
1258 | | Average | | | | 29.7 | |
1259 | ^ | | | | | at | |
1260 | $ | max=50 | | | | | |
1261 |---+---------+--------+--------+--------+-------+------|
1262 #+TBLFM: $6=vsum($P1..$P3)::$7=10*$Tot/$max;%.1f::$at=vmean(&II);%.1f
1264 Important: Please note that for these special tables, recalculating the
1265 table with `C-u C-c *' will only affect rows that are marked `#' or
1266 `*', and named fields. The column formulas are not applied in rows
1267 with empty first field.
1269 The marking characters have the following meaning:
1271 The fields in this line define names for the columns, so that you
1272 may refer to a column as `$Tot' instead of `$6'.
1275 This row defines names for the fields _above_ the row. With such
1276 a definition, any formula in the table may use `$m1' to refer to
1277 the value `10'. Also, named fields can have their own formula
1278 associated with them.
1281 Similar to `^', but defines names for the fields in the row
1285 Fields in this row can define _parameters_ for formulas. For
1286 example, if a field in a `$' row contains `max=50', then formulas
1287 in this table can refer to the value 50 using `$max'. Parameters
1288 work exactly like constants, only that they can be defined on a
1289 per-table basis. Changing a parameter and then recalculating the
1290 table can be useful.
1293 Fields in this row are automatically recalculated when pressing
1294 <TAB> or <RET> or `S-<TAB>' in this row. Also, this row is
1295 selected for a global recalculation with `C-u C-c *'. Unmarked
1296 lines will be left alone by this command.
1299 Selects this line for global recalculation with `C-u C-c *', but
1300 not for automatic recalculation. Use this when automatic
1301 recalculation slows down editing too much.
1304 Unmarked lines are exempt from recalculation with `C-u C-c *'.
1305 All lines that should be recalculated should be marked with `#' or
1309 File: org, Node: Named-field formulas, Next: Editing/debugging formulas, Prev: Advanced features, Up: Table calculations
1311 3.3.5 Named-field formulas
1312 --------------------------
1314 A named field can have its own formula associated with it. In the
1315 example above, this is used for the `at' field that contains the
1316 average result of the students. To enter a formula for a named field,
1317 just type it into the buffer, preceded by `:='. Or use `C-u C-c ='.
1318 This equation will be stored below the table like `$name=...'. Any
1319 recalculation in the table (even if only requested for the current
1320 line) will also update all named field formulas.
1323 File: org, Node: Editing/debugging formulas, Next: Appetizer, Prev: Named-field formulas, Up: Table calculations
1325 3.3.6 Editing and debugging formulas
1326 ------------------------------------
1328 To edit a column or field formula, use the commands `C-c =' and `C-u
1329 C-c =', respectively. The currently active expression is then
1330 presented as default in the minibuffer, where it may be edited.
1332 Note that making a table field blank does not remove the formula
1333 associated with the field - during the next recalculation the field
1334 will be filled again. To remove a formula from a field, you have to
1335 give an empty reply when prompted for the formula, or to edit the
1338 You may edit the `#+TBLFM' directly and re-apply the changed
1339 equations with `C-c C-c' in that line, or with the normal recalculation
1340 commands in the table.
1342 In particular for large tables with many formulas, it is convenient
1343 to use the command `C-c '' to edit the formulas of the current table in
1344 a separate buffer. That buffer will show the formulas one per line,
1345 and you are free to edit, add and remove formulas. Press `C-c ?' on a
1346 `$...' expression to get information about its interpretation.
1347 Exiting the buffer with `C-c C-c' only stores the modified formulas
1348 below the table. Exiting with `C-u C-c C-c' also applies them to the
1349 entire table. `C-c C-q' exits without installing the changes.
1351 When the evaluation of a formula leads to an error, the field content
1352 becomes the string `#ERROR'. If you would like see what is going on
1353 during variable substitution and calculation in order to find a bug,
1354 turn on formula debugging in the menu and repeat the calculation, for
1355 example by pressing `C-c = <RET>' in a field. Detailed information
1359 File: org, Node: Appetizer, Prev: Editing/debugging formulas, Up: Table calculations
1364 Finally, just to whet your appetite on what can be done with the
1365 fantastic `calc' package, here is a table that computes the Taylor
1366 series for a couple of functions (homework: try that with Excel :-)
1368 |---+-------------+---+-----+--------------------------------------|
1369 | | Func | n | x | Result |
1370 |---+-------------+---+-----+--------------------------------------|
1371 | # | exp(x) | 1 | x | 1 + x |
1372 | # | exp(x) | 2 | x | 1 + x + x^2 / 2 |
1373 | # | exp(x) | 3 | x | 1 + x + x^2 / 2 + x^3 / 6 |
1374 | # | x^2+sqrt(x) | 2 | x=0 | x*(0.5 / 0) + x^2 (2 - 0.25 / 0) / 2 |
1375 | # | x^2+sqrt(x) | 2 | x=1 | 2 + 2.5 x - 2.5 + 0.875 (x - 1)^2 |
1376 | * | tan(x) | 3 | x | 0.0175 x + 1.77e-6 x^3 |
1377 |---+-------------+---+-----+--------------------------------------|
1378 #+TBLFM: $5=taylor($2,$4,$3);n3
1381 File: org, Node: orgtbl-mode, Next: table.el, Prev: Table calculations, Up: Tables
1383 3.4 The Orgtbl minor mode
1384 =========================
1386 If you like the intuitive way the Org-mode table editor works, you
1387 might also want to use it in other modes like text-mode or mail-mode.
1388 The minor mode Orgtbl-mode makes this possible. You can always toggle
1389 the mode with `M-x orgtbl-mode'. To turn it on by default, for example
1392 (add-hook 'mail-mode-hook 'turn-on-orgtbl)
1395 File: org, Node: table.el, Prev: orgtbl-mode, Up: Tables
1397 3.5 The `table.el' package
1398 ==========================
1400 Complex ASCII tables with automatic line wrapping, column- and
1401 row-spanning, and alignment can be created using the Emacs table
1402 package by Takaaki Ota (`http://sourceforge.net/projects/table', and
1403 also part of Emacs 22). When <TAB> or `C-c C-c' is pressed in such a
1404 table, Org-mode will call `table-recognize-table' and move the cursor
1405 into the table. Inside a table, the keymap of Org-mode is inactive.
1406 In order to execute Org-mode-related commands, leave the table.
1409 Recognize `table.el' table. Works when the cursor is in a
1413 Insert a table.el table. If there is already a table at point,
1414 this command converts it between the table.el format and the
1415 Org-mode format. See the documentation string of the command
1416 `org-convert-table' for the restrictions under which this is
1420 File: org, Node: Hyperlinks, Next: TODO items, Prev: Tables, Up: Top
1425 Just like HTML, Org-mode provides links inside a file, and external
1426 links to other files, Usenet articles, emails, and much more.
1430 * Link format:: How links in Org-mode are formatted
1431 * Internal links:: Links to other places in the current file
1432 * External links:: URL-like links to the world
1433 * Handling links:: Creating, inserting and following
1434 * Search options:: Linking to a specific location
1435 * Custom searches:: When the default search is not enough
1436 * Remember:: Org-trees store quick notes
1439 File: org, Node: Link format, Next: Internal links, Prev: Hyperlinks, Up: Hyperlinks
1444 Org-mode will recognize plain URL-like links and activate them as
1445 clickable links. The general link format, however, looks like this:
1447 [[link][description]] or alternatively [[link]]
1449 Once a link in the buffer is complete (all brackets present),
1450 Org-mode will change the display so that `description' is displayed
1451 instead of `[[link][description]]' and `link' is displayed instead of
1452 `[[link]]'. Links will be highlighted in the face `org-link', which by
1453 default is an underlined face. You can directly edit the visible part
1454 of a link. Note that this can be either the `link' part (if there is
1455 no description) or the `description' part. To edit also the invisible
1456 `link' part, use `C-c C-l' with the cursor on the link.
1458 If you place the cursor at the beginning or just behind the end of
1459 the displayed text and press <BACKSPACE>, you will remove the
1460 (invisible) bracket at that location. This makes the link incomplete
1461 and the internals are again displayed as plain text. Inserting the
1462 missing bracket hides the link internals again. To show the internal
1463 structure of all links, use the menu entry `Org->Hyperlinks->Literal
1467 File: org, Node: Internal links, Next: External links, Prev: Link format, Up: Hyperlinks
1472 If the link does not look like a URL, it is considered to be internal in
1473 the current file. Links such as `[[My Target]]' or `[[My Target][Find
1474 my target]]' lead to a text search in the current file. The link can
1475 be followed with `C-c C-o' when the cursor is on the link, or with a
1476 mouse click (*note Handling links::). The preferred match for such a
1477 link is a dedicated target: the same string in double angular brackets.
1478 Targets may be located anywhere; often it is convenient to put them
1479 into a comment line. For example
1483 In HTML export (*note HTML export::), such targets will become named
1484 anchors for direct access through `http' links(1).
1486 If no dedicated target exists, Org-mode will search for the words in
1487 the link. In the above example the search would be for `my target'.
1488 Links starting with a star like `*My Target' restrict the search to
1489 headlines. When searching, Org-mode will first try an exact match, but
1490 then move on to more and more lenient searches. For example, the link
1491 `[[*My Targets]]' will find any of the following:
1494 ** TODO my targets are bright
1495 ** my 20 targets are
1497 To insert a link targeting a headline, in-buffer completion can be
1498 used. Just type a star followed by a few optional letters into the
1499 buffer and press `M-<TAB>'. All headlines in the current buffer will be
1500 offered as completions. *Note Handling links::, for more commands
1503 Following a link pushes a mark onto Org-mode's own mark ring. You
1504 can return to the previous position with `C-c &'. Using this command
1505 several times in direct succession goes back to positions recorded
1510 * Radio targets:: Make targets trigger links in plain text.
1511 * CamelCase links:: Activating CamelCase words as links
1513 ---------- Footnotes ----------
1515 (1) Note that text before the first headline will never be exported,
1516 so the first such target must be after the first headline.
1519 File: org, Node: Radio targets, Next: CamelCase links, Prev: Internal links, Up: Internal links
1524 You can configure Org-mode to link any occurrences of certain target
1525 names in normal text. So without explicitly creating a link, the text
1526 connects to the target radioing its position. Radio targets are
1527 enclosed by triple angular brackets. For example, a target `<<<My
1528 Target>>>' causes each occurrence of `my target' in normal text to
1529 become activated as a link. The Org-mode file is scanned automatically
1530 for radio targets only when the file is first loaded into Emacs. To
1531 update the target list during editing, press `C-c C-c' with the cursor
1535 File: org, Node: CamelCase links, Prev: Radio targets, Up: Internal links
1537 4.2.2 CamelCase words as links
1538 ------------------------------
1540 Org-mode also supports CamelCase words as links. This feature is not
1541 turned on by default because of the inconsistencies this system suffers
1542 from. To activate CamelCase words as links, you need to customize the
1543 option `org-activate-links'. A CamelCase word then leads to a text
1544 search such that `CamelCaseLink' is equivalent to `[[camel case link]]'.
1547 File: org, Node: External links, Next: Handling links, Prev: Internal links, Up: Hyperlinks
1552 Org-mode supports links to files, websites, Usenet and email messages,
1553 and BBDB database entries. External links are URL-like locators. They
1554 start with a short identifying string followed by a colon. There can be
1555 no space after the colon. The following list shows examples for each
1558 http://www.astro.uva.nl/~dominik on the web
1559 file:/home/dominik/images/jupiter.jpg file, absolute path
1560 file:papers/last.pdf file, relative path
1561 news:comp.emacs Usenet link
1562 mailto:adent@galaxy.net Mail link
1563 vm:folder VM folder link
1564 vm:folder#id VM message link
1565 vm://myself@some.where.org/folder#id VM on remote machine
1566 wl:folder WANDERLUST folder link
1567 wl:folder#id WANDERLUST message link
1568 mhe:folder MH-E folder link
1569 mhe:folder#id MH-E message link
1570 rmail:folder RMAIL folder link
1571 rmail:folder#id RMAIL message link
1572 gnus:group GNUS group link
1573 gnus:group#id GNUS article link
1574 bbdb:Richard Stallman BBDB link
1575 shell:ls *.org A shell command
1576 elisp:(find-file-other-frame "Elisp.org") An elisp form to evaluate
1578 A link should be enclosed in double brackets and may contain a
1579 descriptive text to be displayed instead of the url (*note Link
1580 format::), for example:
1582 [[http://www.gnu.org/software/emacs/][GNU Emacs]]
1584 Org-mode also finds external links in the normal text and activates
1585 them as links. If spaces must be part of the link (for example in
1586 `bbdb:Richard Stallman'), or you need to remove ambiguities about the
1587 end of the link, enclose them in angular brackets.
1590 File: org, Node: Handling links, Next: Search options, Prev: External links, Up: Hyperlinks
1595 Org-mode provides methods to create a link in the correct syntax, to
1596 insert it into an org-mode file, and to follow the link.
1599 Store a link to the current location. This is a _global_ command
1600 which can be used in any buffer to create a link. The link will be
1601 stored for later insertion into an Org-mode buffer (see below).
1602 For Org-mode files, if there is a `<<target>>' at the cursor, the
1603 link points to the target. Otherwise it points to the current
1604 headline. For VM, RMAIL, WANDERLUST, MH-E, GNUS and BBDB buffers,
1605 the link will indicate the current article/entry. For W3 and W3M
1606 buffers, the link goes to the current URL. For any other files,
1607 the link will point to the file, with a search string (*note
1608 Search options::) pointing to the contents of the current line.
1609 If there is an active region, the selected words will form the
1610 basis of the search string. If the automatically created link is
1611 not working correctly or accurately enough, you can write custom
1612 functions to select the search string and to do the search for
1613 particular file types - see *Note Custom searches::. The key
1614 binding `C-c l' is only a suggestion - see *Note Installation::.
1617 Insert a link. This prompts for a link to be inserted into the
1618 buffer. You can just type a link, using text for an internal
1619 link, or one of the link type prefixes mentioned in the examples
1620 above. Through completion, all links stored during the current
1621 session can be accessed(1). The link will be inserted into the
1622 buffer, along with a descriptive text. Note that you don't have
1623 to use this command to insert a link. Links in Org-mode are plain
1624 text, and you can type or paste them straight into the buffer. By
1625 using this command, the links are automatically enclosed in double
1626 brackets, and you will be asked for the optional descriptive text.
1627 If the link is a `file:' link and the linked file is located in
1628 the same directory as the current file or a subdirectory of it, the
1629 path of the file will be inserted relative to the current
1633 When `C-c C-l' is called with a `C-u' prefix argument, a link to a
1634 file will be inserted and you may use file name completion to
1635 select the name of the file. The path to the file is inserted
1636 relative to the directory of the current org file, if the linked
1637 file is in the current directory or in a subdirectory of it, or if
1638 the path is written relative to the current directory using `../'.
1639 Otherwise an absolute path is used, if possible with `~/' for
1640 your home directory. You can force an absolute path with two
1643 `C-c C-l with cursor on existing link'
1644 When the cursor is on an existing link, `C-c C-l' allows you to
1645 edit the link and description parts of the link.
1648 Open link at point. This will launch a web browser for URLs (using
1649 `browse-url-at-point'), run vm/mh-e/wanderlust/rmail/gnus/bbdb for
1650 the corresponding links, and execute the command in a shell link.
1651 When the cursor is on an internal link, this commands runs the
1652 corresponding search. When the cursor is on a TAG list in a
1653 headline, it creates the corresponding TAGS view. If the cursor
1654 is on a time stamp, it compiles the agenda for that date.
1655 Furthermore, it will visit text and remote files in `file:' links
1656 with Emacs and select a suitable application for local non-text
1657 files. Classification of files is based on file extension only.
1658 See option `org-file-apps'. If you want to override the default
1659 application and visit the file with Emacs, use a `C-u' prefix.
1663 On links, `mouse-2' will open the link just as `C-c C-o' would.
1664 Under Emacs 22, also `mouse-1' will follow a link.
1667 Like `mouse-2', but force file links to be opened with Emacs.
1670 Push the current position onto the mark ring, to be able to return
1671 easily. Commands following an internal link do this automatically.
1674 Jump back to a recorded position. A position is recorded by the
1675 commands following internal links, and by `C-c %'. Using this
1676 command several times in direct succession moves through a ring of
1677 previously recorded positions.
1679 ---------- Footnotes ----------
1681 (1) After insertion of a stored link, the link will be removed from
1682 the list of stored links. To keep it in the list later use, use a
1683 triple `C-u' prefix to `C-c C-l', or configure the option
1684 `org-keep-stored-link-after-insertion'.
1687 File: org, Node: Search options, Next: Custom searches, Prev: Handling links, Up: Hyperlinks
1689 4.5 Search options in file links
1690 ================================
1692 File links can contain additional information to make Emacs jump to a
1693 particular location in the file when following a link. This can be a
1694 line number or a search option after a double(1) colon. For example,
1695 when the command `C-c l' creates a link (*note Handling links::) to a
1696 file, it encodes the words in the current line as a search string that
1697 can be used to find this line back later when following the link with
1700 Here is the syntax of the different ways to attach a search to a file
1701 link, together with an explanation:
1703 [[file:~/code/main.c::255]]
1704 [[file:~/xx.org::My Target]]
1705 [[file:~/xx.org::*My Target]]
1706 [[file:~/xx.org::/regexp/]]
1712 Search for a link target `<<My Target>>', or do a text search for
1713 `my target', similar to the search in internal links, see *Note
1714 Internal links::. In HTML export (*note HTML export::), such a
1715 file link will become an HTML reference to the corresponding named
1716 anchor in the linked file.
1719 In an Org-mode file, restrict search to headlines.
1722 Do a regular expression search for `regexp'. This uses the Emacs
1723 command `occur' to list all matches in a separate window. If the
1724 target file is in Org-mode, `org-occur' is used to create a sparse
1725 tree with the matches.
1727 As a degenerate case, a file link with an empty file name can be used
1728 to search the current file. For example, `<file:::find me>' does a
1729 search for `find me' in the current file, just as `[[find me]]' would.
1731 ---------- Footnotes ----------
1733 (1) For backward compatibility, line numbers can also follow a
1737 File: org, Node: Custom searches, Next: Remember, Prev: Search options, Up: Hyperlinks
1742 The default mechanism for creating search strings and for doing the
1743 actual search related to a file link may not work correctly in all
1744 cases. For example, BibTeX database files have many entries like
1745 `year="1993"' which would not result in good search strings, because
1746 the only unique identification for a BibTeX entry is the citation key.
1748 If you come across such a problem, you can write custom functions to
1749 set the right search string for a particular file type, and to do the
1750 search for the string in the file. Using `add-hook', these functions
1751 need to be added to the hook variables
1752 `org-create-file-search-functions' and
1753 `org-execute-file-search-functions'. See the docstring for these
1754 variables for more information. Org-mode actually uses this mechanism
1755 for BibTeX database files, and you can use the corresponding code as an
1756 implementation example. Search for `BibTeX links' in the source file.
1759 File: org, Node: Remember, Prev: Custom searches, Up: Hyperlinks
1764 Another way to create org entries with links to other files is through
1765 the _Remember_ package by John Wiegley. _Remember_ lets you store
1766 quick notes with little interruption of your work flow. See
1767 `http://www.emacswiki.org/cgi-bin/wiki/RememberMode' for more
1768 information. The notes produced by _Remember_ can be stored in
1769 different ways, and Org-mode files are a good target. Org-mode allows
1770 you to file away notes either to a default file, or directly to the
1771 correct location in your Org-mode outline tree. The following
1772 customization will tell _Remember_ to use org files as target, and to
1773 create annotations compatible with Org-mode links.
1775 (setq org-directory "~/path/to/my/orgfiles/")
1776 (setq org-default-notes-file "~/.notes")
1777 (setq remember-annotation-functions '(org-remember-annotation))
1778 (setq remember-handler-functions '(org-remember-handler))
1779 (add-hook 'remember-mode-hook 'org-remember-apply-template)
1781 In combination with Org-mode, you can use templates to generate
1782 different types of remember notes. For example, if you would like to
1783 use one template to create general TODO entries, and another one for
1784 journal entries, you could use:
1786 (setq org-remember-templates
1787 '((?t "* TODO %?\n %i\n %a" "~/org/TODO.org")
1788 (?j "* %U %?\n\n %i\n %a" "~/org/JOURNAL.org")))
1790 In these entries, the character specifies how to select the template,
1791 the first string specifies the template, and the (optional) second
1792 string specifies a default file (overruling `org-default-notes-file')
1793 as a target for this note.
1795 When you call `M-x remember' to remember something, org will prompt
1796 for a key to select the template and then prepare the buffer like
1798 <file:link to where you called remember>
1802 * [2006-03-21 Tue 15:37]
1804 <file:link to where you called remember>
1806 See the variable `org-remember-templates' for more details.
1808 When you are finished composing a note with remember, you have to
1809 press `C-c C-c' to file the note away. The handler first prompts for a
1810 target file - if you press <RET>, the value of `org-default-notes-file'
1811 is used. Then the command offers the headings tree of the selected
1812 file. You can either immediately press <RET> to get the note appended
1813 to the file. Or you can use vertical cursor motion (<up> and <down>)
1814 and visibility cycling (<TAB>) to find a better place. Pressing <RET>
1815 or <left> or <right> leads to the following result.
1817 Cursor Key Note gets inserted
1819 buffer-start <RET> as level 2 heading at end of file
1820 on headline <RET> as sublevel of the heading at cursor
1821 <left> as same level, before current heading
1822 <right> as same level, after current heading
1823 not on <RET> at cursor position, level taken from context.
1824 headline Or use prefix arg to specify level
1827 So a fast way to store the note is to press `C-c C-c <RET> <RET>' to
1828 append it to the default file. Even shorter would be `C-u C-c C-c',
1829 which does the same without even showing the tree. But with little
1830 extra effort, you can push it directly to the correct location.
1832 Before inserting the text into a tree, the function ensures that the
1833 text has a headline, i.e. a first line that starts with a `*'. If not,
1834 a headline is constructed from the current date and some additional
1835 data. If the variable `org-adapt-indentation' is non-nil, the entire
1836 text is also indented so that it starts in the same column as the
1837 headline (after the asterisks).
1840 File: org, Node: TODO items, Next: Timestamps, Prev: Hyperlinks, Up: Top
1845 Org-mode does not maintain TODO lists as a separate document. TODO
1846 items are an integral part of the notes file, because TODO items
1847 usually come up while taking notes! With Org-mode, you simply mark any
1848 entry in a tree as being a TODO item. In this way, the information is
1849 not duplicated, and the entire context from which the item emerged is
1850 always present when you check.
1852 Of course, this technique causes TODO items to be scattered
1853 throughout your file. Org-mode provides methods to give you an
1854 overview over all things you have to do.
1858 * TODO basics:: Marking and displaying TODO entries
1859 * TODO extensions:: Workflow and assignments
1860 * Priorities:: Some things are more important than others
1861 * Breaking down tasks:: Splitting a task into managable pieces
1862 * Checkboxes:: Tick-off lists
1865 File: org, Node: TODO basics, Next: TODO extensions, Prev: TODO items, Up: TODO items
1867 5.1 Basic TODO functionality
1868 ============================
1870 Any headline can become a TODO item by starting it with the word TODO,
1873 *** TODO Write letter to Sam Fortune
1875 The most important commands to work with TODO entries are:
1878 Rotate the TODO state of the current item between
1880 ,-> (unmarked) -> TODO -> DONE --.
1881 '--------------------------------'
1883 The same rotation can also be done "remotely" from the timeline and
1884 agenda buffers with the `t' command key (*note Agenda commands::).
1888 Select the following/preceding TODO state, similar to cycling.
1889 Mostly useful if more than two TODO states are possible (*note
1893 View TODO items in a _sparse tree_ (*note Sparse trees::). Folds
1894 the entire buffer, but shows all TODO items and the headings
1895 hierarchy above them. With prefix arg, show also the DONE
1896 entries. With numerical prefix N, show the tree for the Nth
1897 keyword in the variable `org-todo-keywords'.
1900 Show the global TODO list. This collects the TODO items from all
1901 agenda files (*note Agenda views::) into a single buffer. The
1902 buffer is in `agenda-mode', so there are commands to examine and
1903 manipulate the TODO entries directly from that buffer (*note
1904 Agenda commands::). *Note Global TODO list::, for more
1908 File: org, Node: TODO extensions, Next: Priorities, Prev: TODO basics, Up: TODO items
1910 5.2 Extended use of TODO keywords
1911 =================================
1913 The default implementation of TODO entries is just two states: TODO and
1914 DONE. You can, however, use the TODO feature for more complicated
1915 things by configuring the variables `org-todo-keywords' and
1916 `org-todo-interpretation'. Using special setup, you can even use TODO
1917 keywords in different ways in different org files.
1919 Note that tags are another way to classify headlines in general and
1920 TODO items in particular (*note Tags::).
1924 * Workflow states:: From TODO to DONE in steps
1925 * TODO types:: I do this, Fred the rest
1926 * Per file keywords:: Different files, different requirements
1929 File: org, Node: Workflow states, Next: TODO types, Prev: TODO extensions, Up: TODO extensions
1931 5.2.1 TODO keywords as workflow states
1932 --------------------------------------
1934 You can use TODO keywords to indicate different states in the process
1935 of working on an item, for example:
1937 (setq org-todo-keywords '("TODO" "FEEDBACK" "VERIFY" "DONE")
1938 org-todo-interpretation 'sequence)
1940 Changing these variables only becomes effective in a new Emacs
1941 session. With this setup, the command `C-c C-t' will cycle an entry
1942 from TODO to FEEDBACK, then to VERIFY, and finally to DONE. You may
1943 also use a prefix argument to quickly select a specific state. For
1944 example `C-3 C-c C-t' will change the state immediately to VERIFY. If
1945 you define many keywords, you can use in-buffer completion (see *Note
1946 Completion::) to insert these words into the buffer.
1949 File: org, Node: TODO types, Next: Per file keywords, Prev: Workflow states, Up: TODO extensions
1951 5.2.2 TODO keywords as types
1952 ----------------------------
1954 The second possibility is to use TODO keywords to indicate different
1955 types of action items. For example, you might want to indicate that
1956 items are for "work" or "home". If you are into David Allen's _Getting
1957 Things DONE_, you might want to use todo types `NEXTACTION', `WAITING',
1958 `MAYBE'. Or, when you work with several people on a single project,
1959 you might want to assign action items directly to persons, by using
1960 their names as TODO keywords. This would be set up like this:
1962 (setq org-todo-keywords '("Fred" "Sara" "Lucy" "Mike" "DONE")
1963 org-todo-interpretation 'type)
1965 In this case, different keywords do not indicate a sequence, but
1966 rather different types. So it is normally not useful to change from
1967 one type to another. Therefore, in this case the behavior of the
1968 command `C-c C-t' is changed slightly(1). When used several times in
1969 succession, it will still cycle through all names. But when you return
1970 to the item after some time and execute `C-c C-t' again, it will switch
1971 from each name directly to DONE. Use prefix arguments or completion to
1972 quickly select a specific name. You can also review the items of a
1973 specific TODO type in a sparse tree by using a numeric prefix to `C-c
1974 C-v'. For example, to see all things Lucy has to do, you would use
1975 `C-3 C-c C-v'. To collect Lucy's items from all agenda files into a
1976 single buffer, you would use the prefix arg as well when creating the
1977 global todo list: `C-3 C-c t'.
1979 ---------- Footnotes ----------
1981 (1) This is also true for the `t' command in the timeline and agenda
1985 File: org, Node: Per file keywords, Prev: TODO types, Up: TODO extensions
1987 5.2.3 Setting up TODO keywords for individual files
1988 ---------------------------------------------------
1990 It can be very useful to use different aspects of the TODO mechanism in
1991 different files, which is not possible with the global settings
1992 described above. For file-local settings, you need to add special
1993 lines to the file which set the keywords and interpretation for that
1994 file only. For example, to set one of the two examples discussed
1995 above, you need one of the following lines, starting in column zero
1996 anywhere in the file:
1998 #+SEQ_TODO: TODO FEEDBACK VERIFY DONE
1999 #+TYP_TODO: Fred Sara Lucy Mike DONE
2001 To make sure you are using the correct keyword, type `#+' into the
2002 buffer and then use `M-<TAB>' completion.
2004 Remember that the last keyword must always mean that the item is DONE
2005 (although you may use a different word). Also note that in each file,
2006 only one of the two aspects of TODO keywords can be used. After
2007 changing one of these lines, use `C-c C-c' with the cursor still in the
2008 line to make the changes known to Org-mode(1).
2010 If you want to use very many keywords, for example when working with
2011 a large group of people, you may split the names over several lines:
2013 #+TYP_TODO: Fred Sara Lucy Mike
2014 #+TYP_TODO: Luis George Jules Jessica
2015 #+TYP_TODO: Kim Arnold Peter
2018 ---------- Footnotes ----------
2020 (1) Org-mode parses these lines only when Org-mode is activated
2021 after visiting a file. `C-c C-c' with the cursor in a line starting
2022 with `#+' is simply restarting Org-mode for the current buffer.
2025 File: org, Node: Priorities, Next: Breaking down tasks, Prev: TODO extensions, Up: TODO items
2030 If you use Org-mode extensively to organize your work, you may end up
2031 with a number of TODO entries so large that you'd like to prioritize
2032 them. This can be done by placing a _priority cookie_ into the
2035 *** TODO [#A] Write letter to Sam Fortune
2037 With its standard setup, Org-mode supports priorities `A', `B', and
2038 `C'. `A' is the highest priority. An entry without a cookie is
2039 treated as priority `B'. Priorities make a difference only in the
2040 agenda (*note Weekly/Daily agenda::).
2043 Set the priority of the current headline. The command prompts for
2044 a priority character `A', `B' or `C'. When you press <SPC>
2045 instead, the priority cookie is removed from the headline. The
2046 priorities can also be changed "remotely" from the timeline and
2047 agenda buffer with the `,' command (*note Agenda commands::).
2051 Increase/decrease priority of current headline. Note that these
2052 keys are also used to modify time stamps (*note Creating
2053 timestamps::). Furthermore, these keys are also used by CUA-mode
2054 (*note Conflicts::).
2057 File: org, Node: Breaking down tasks, Next: Checkboxes, Prev: Priorities, Up: TODO items
2059 5.4 Breaking tasks down into subtasks
2060 =====================================
2062 It is often advisable to break down large tasks into smaller, managable
2063 subtasks. You can do this by creating an outline tree below a TODO
2064 item, with detailed subtasks on the tree(1). Another possibility is
2065 the use of checkboxes to ideantify (a hierarchy of) a large number of
2066 subtasks (*note Checkboxes::).
2068 ---------- Footnotes ----------
2070 (1) To keep subtasks out of the global TODO list, see the
2071 `org-agenda-todo-list-sublevels'.
2074 File: org, Node: Checkboxes, Prev: Breaking down tasks, Up: TODO items
2079 Every item in a plain list (*note Plain lists::) can be made a checkbox
2080 by starting it with the string `[ ]'. This feature is similar to TODO
2081 items (*note TODO items::), but more lightweight. Checkboxes are not
2082 included into the global TODO list, so they are often great to split a
2083 task into a number of simple steps. Or you can use them in a shopping
2084 list to select the items you need to buy. To toggle a checkbox, use
2085 `C-c C-c', or try Piotr Zielinski's `org-mouse.el'. Here is an example
2088 * TODO Organize party [3/6]
2094 - [ ] think about what music to play
2095 - [X] talk to the neighbors
2097 The `[3/6]' and `[1/3]' in the first and second line are cookies
2098 indicating how many checkboxes are present in this entry, and how many
2099 of them have been checked off. This can give you an idea on how many
2100 checkboxes remain, even without opening a folded entry. The cookies
2101 can be placed into a headline or into (the first line of) a plain list
2102 item. Each cookie covers all checkboxes structurally below that
2103 headline/item. You have to insert the cookie yourself by typing either
2104 `[/]' or `[%]'. In the first case you get an `n out of m' result, in
2105 the second case you get information about the percentage of checkboxes
2106 checked (in the above example, this would be `[50%]' and `[33%],
2109 The following commands work with checkboxes:
2112 Toggle checkbox at point.
2115 Toggle checkbox at point.
2116 - If there is an active region, toggle the first checkbox in
2117 the region and set all remaining boxes to the same status as
2118 the first. If you want to toggle all boxes in the region
2119 independently, use a prefix argument.
2121 - If the cursor is in a headline, toggle checkboxes in the
2122 region between this headline and the next. This does _not_
2123 act on the entire subtree, just the current entry.
2125 - If no active region, just toggle the checkbox at point.
2128 Insert a new item with a checkbox. This works only if the cursor
2129 is already in a plain list item (*note Plain lists::).
2132 Update the checkbox statistics in the current outline entry. When
2133 called with a `C-u' prefix, update the entire file. Checkbox
2134 statistic cookies are updated automatically if you toggle
2135 checkboxes with `C-c C-c' and make new ones with `M-S-<RET>'. If
2136 you delete boxes or add/change them by hand, use this command to
2137 get things back into synch. Or simply toggle any checkbox twice
2141 File: org, Node: Timestamps, Next: Tags, Prev: TODO items, Up: Top
2146 Items can be labeled with timestamps to make them useful for project
2151 * Time stamps:: Assigning a time to a tree entry
2152 * Creating timestamps:: Commands which insert timestamps
2153 * Progress logging:: Documenting when what work was done.
2156 File: org, Node: Time stamps, Next: Creating timestamps, Prev: Timestamps, Up: Timestamps
2158 6.1 Time stamps, deadlines and scheduling
2159 =========================================
2161 A time stamp is a specification of a date (possibly with time) in a
2162 special format, either `<2003-09-16 Tue>' or `<2003-09-16 Tue 09:39>'.
2163 A time stamp can appear anywhere in the headline or body of an org-tree
2164 entry. Its presence allows entries to be shown on specific dates in
2165 the agenda (*note Weekly/Daily agenda::). We distinguish:
2168 A simple time stamp just assigns a date/time to an item. This is
2169 just like writing down an appointment in a paper agenda, or like
2170 writing down an event in a diary, when you want to take note of
2171 when something happened. In the timeline and agenda displays, the
2172 headline of an entry associated with a plain time stamp will be
2173 shown exactly on that date.
2176 Two time stamps connected by `--' denote a time range. The
2177 headline will be shown on the first and last day of the range, and
2178 on any dates that are displayed and fall in the range. Here is an
2181 ** Meeting in Amsterdam
2182 <2004-08-23 Mon>--<2004-08-26 Thu>
2184 TIME STAMP WITH SCHEDULED KEYWORD
2185 If a time stamp is preceded by the word `SCHEDULED:', it means you
2186 are planning to start working on that task on the given date. So
2187 this is not about recording an event, but about planning your
2188 work. The headline will be listed under the given date. In
2189 addition, a reminder that the scheduled date has passed will be
2190 present in the compilation for _today_, until the entry is marked
2191 DONE. I.e., the task will automatically be forwarded until
2194 *** TODO Call Trillian for a date on New Years Eve.
2195 SCHEDULED: <2004-12-25 Sat>
2197 TIME STAMP WITH DEADLINE KEYWORD
2198 If a time stamp is preceded by the word `DEADLINE:', the task
2199 (most likely a TODO item) is supposed to be finished on that date,
2200 and it will be listed then. In addition, the compilation for
2201 _today_ will carry a warning about the approaching or missed
2202 deadline, starting `org-deadline-warning-days' before the due
2203 date, and continuing until the entry is marked DONE. An example:
2205 *** TODO write article about the Earth for the Guide
2206 The editor in charge is <bbdb:Ford Prefect>
2207 DEADLINE: <2004-02-29 Sun>
2209 TIME STAMP WITH CLOSED KEYWORD
2210 When `org-log-done' is non-nil, Org-mode will automatically insert
2211 a special time stamp each time a TODO entry is marked done (*note
2212 Progress logging::). This time stamp is enclosed in square
2213 brackets instead of angular brackets.
2215 TIME RANGE WITH CLOCK KEYWORD
2216 When using the clock to time the work that is being done on
2217 specific items, time ranges preceded by the CLOCK keyword are
2218 inserted automatically into the file. The time stamps are
2219 enclosed in square brackets instead of angular brackets. *Note
2220 Clocking work time::.
2223 File: org, Node: Creating timestamps, Next: Progress logging, Prev: Time stamps, Up: Timestamps
2225 6.2 Creating timestamps
2226 =======================
2228 For Org-mode to recognize time stamps, they need to be in the specific
2229 format. All commands listed below produce time stamps in the correct
2233 Prompt for a date and insert a corresponding time stamp. When the
2234 cursor is at a previously used time stamp, it is updated to NOW.
2235 When this command is used twice in succession, a time range is
2239 Like `C-c .', but use the alternative format which contains date
2240 and time. The default time can be rounded to multiples of 5
2241 minutes, see the option `org-time-stamp-rounding-minutes'.
2244 Like `C-c .', but insert an inactive time stamp not triggering the
2248 Insert a time stamp corresponding to the cursor date in the
2252 Access the Emacs calendar for the current date. If there is a
2253 timestamp in the current line, goto the corresponding date instead.
2256 Access the agenda for the date given by the time stamp at point
2257 (*note Weekly/Daily agenda::).
2260 Insert `DEADLINE' keyword along with a stamp. The insertion will
2261 happen in the line directly following the headline.
2264 Create a sparse tree with all deadlines that are either past-due,
2265 or which will become due within `org-deadline-warning-days'. With
2266 `C-u' prefix, show all deadlines in the file. With a numeric
2267 prefix, check that many days. For example, `C-1 C-c C-w' shows
2268 all deadlines due tomorrow.
2271 Insert `SCHEDULED' keyword along with a stamp. The insertion will
2272 happen in the line directly following the headline. Any CLOSED
2273 timestamp will be removed.
2277 Change date at cursor by one day. These key bindings conflict with
2278 CUA-mode (*note Conflicts::).
2282 Change the item under the cursor in a timestamp. The cursor can
2283 be on a year, month, day, hour or minute. Note that if the cursor
2284 is not at a time stamp, these same keys modify the priority of an
2285 item. (*note Priorities::). The key bindings also conflict with
2286 CUA-mode (*note Conflicts::).
2289 Evaluate a time range by computing the difference between start and
2290 end. With prefix arg, insert result after the time range (in a
2291 table: into the following column).
2293 When Org-mode prompts for a date/time, the function reading your
2294 input will replace anything you choose not to specify with the current
2295 date and time. For details, see the documentation string of
2296 `org-read-date'. Also, a calender will pop up to allow selecting a
2297 date. The calendar can be fully controlled from the minibuffer, and a
2298 date can be selected with the following commands:
2301 Scroll calendar backwards by one month.
2304 Scroll calendar forwards by one month.
2307 Select date by clicking on it.
2328 Choose date in calendar (only if nothing typed into minibuffer).
2331 File: org, Node: Progress logging, Prev: Creating timestamps, Up: Timestamps
2333 6.3 Progress Logging
2334 ====================
2336 Org-mode can automatically record a time stamp when you mark a TODO item
2337 as DONE. You can also measure precisely the time you spent on specific
2338 items in a project by starting and stopping a clock when you start and
2339 stop working on an aspect of a project.
2343 * Closing items:: When was this entry marked DONE?
2344 * Clocking work time:: When exactly did you work on this item?
2347 File: org, Node: Closing items, Next: Clocking work time, Prev: Progress logging, Up: Progress logging
2352 If you want to keep track of _when_ a certain TODO item was finished,
2353 turn on logging with
2355 (setq org-log-done t)
2357 Then each time you turn a TODO entry into DONE using either `C-c C-t'
2358 in the Org-mode buffer or `t' in the agenda buffer, a line `CLOSED:
2359 [timestamp]' will be inserted just after the headline. If you turn the
2360 entry back into a TODO item again through further state cycling, that
2361 line will be removed again. In the timeline (*note Timeline::) and in
2362 the agenda (*note Weekly/Daily agenda::), you can then use the `l' key
2363 to display the TODO items closed on each day, giving you an overview of
2364 what has been done on a day.
2367 File: org, Node: Clocking work time, Prev: Closing items, Up: Progress logging
2369 6.3.2 Clocking work time
2370 ------------------------
2372 Org-mode allows you to clock the time you spent on specific tasks in a
2373 project. When you start working on an item, you can start the clock.
2374 When you stop working on that task, or when you mark the task done, the
2375 clock is stopped and the corresponding time interval is recorded. It
2376 also computes the total time spent on each subtree of a project.
2379 Start the clock on the current item (clock-in). This inserts the
2380 CLOCK keyword together with a timestamp.
2383 Stop the clock (clock-out). The inserts another timestamp at the
2384 same location where the clock was last started. It also directly
2385 computes the resulting time in inserts it after the time range as
2389 Recompute the time interval after changing one of the time stamps.
2390 This is only necessary if you edit the time stamps directly. If
2391 you change them with `S-<cursor>' keys, the update is automatic.
2394 Changing the TODO state of an item to DONE automatically stops the
2395 clock if it is running in this same item.
2398 Cancel the current clock. This is useful if a clock was started by
2399 mistake, or if you ended up working on something else.
2402 Display time summaries for each subtree in the current buffer.
2403 This puts overlays at the end of each headline, showing the total
2404 time recorded under that heading, including the time of any
2405 subheadings. You can use visibility cycling to study the tree, but
2406 the overlays disappear automatically when the buffer is changed.
2409 Insert a dynamic block (*note Dynamic blocks::) containing a clock
2410 report as an org-mode table into the current file.
2411 #+BEGIN: clocktable :maxlevel 2 :emphasize nil
2414 If such a block already exists, its content is replaced by the new
2415 table. The `BEGIN' line can specify options:
2416 :maxlevels Maximum level depth to which times are listed in the table.
2417 :emphasize When `t', emphasize level one and level two items
2418 :block The time block to consider. This block is specified relative
2419 to the current time and may be any of these keywords:
2420 `today', `yesterday', `thisweek', `lastweek',
2421 `thismonth', `lastmonth', `thisyear', or `lastyear'.
2422 :tstart A time string specifying when to start considering times
2423 :tend A time string specifying when to stop considering times
2424 So to get a clock summary for the current day, you could write
2425 #+BEGIN: clocktable :maxlevel 2 :block today
2428 and to use a specific time range you could write(1)
2429 #+BEGIN: clocktable :tstart "<2006-08-10 Thu 10:00>"
2430 :tend "<2006-08-10 Thu 12:00>"
2435 Update all dynamic blocks (*note Dynamic blocks::). This is
2436 useful if you have several clocktable blocks in a buffer.
2438 The `l' key may be used in the timeline (*note Timeline::) and in
2439 the agenda (*note Weekly/Daily agenda::) to show which tasks have been
2440 worked on or closed during a day.
2442 ---------- Footnotes ----------
2444 (1) Note that all parameters must be specified in a single line -
2445 the line is broken here only to fit it onto the manual.
2448 File: org, Node: Tags, Next: Agenda views, Prev: Timestamps, Up: Top
2453 If you wish to implement a system of labels and contexts for
2454 cross-correlating information, an excellent way is to assign tags to
2455 headlines. Org-mode has extensive support for using tags.
2457 Every headline can contain a list of tags, at the end of the
2458 headline. Tags are normal words containing letters, numbers, `_', and
2459 `@'. Tags must be preceded and followed by a single colon; like
2460 `:WORK:'. Several tags can be specified like `:WORK:URGENT:'.
2464 * Tag inheritance:: Tags use the tree structure of the outline
2465 * Setting tags:: How to assign tags to a headline
2466 * Tag searches:: Searching for combinations of tags
2469 File: org, Node: Tag inheritance, Next: Setting tags, Prev: Tags, Up: Tags
2474 Tags make use of the hierarchical structure of outline trees. If a
2475 heading has a certain tag, all subheadings will inherit the tag as
2476 well. For example, in the list
2478 * Meeting with the French group :WORK:
2479 ** Summary by Frank :BOSS:NOTES:
2480 *** TODO Prepare slides for him :ACTION:
2482 the final heading will have the tags `:WORK:', `:BOSS:', `:NOTES:', and
2483 `:ACTION:'. When executing tag searches and Org-mode finds that a
2484 certain headline matches the search criterion, it will not check any
2485 sublevel headline, assuming that these likely also match, and that the
2486 list of matches can become very long. This may not be what you want,
2487 however, and you can influence inheritance and searching using the
2488 variables `org-use-tag-inheritance' and `org-tags-match-list-sublevels'.
2491 File: org, Node: Setting tags, Next: Tag searches, Prev: Tag inheritance, Up: Tags
2496 Tags can simply be typed into the buffer at the end of a headline.
2497 After a colon, `M-<TAB>' offers completion on tags. There is also a
2498 special command for inserting tags:
2501 Enter new tags for the current headline. Org-mode will either
2502 offer completion or a special single-key interface for setting
2503 tags, see below. After pressing <RET>, the tags will be inserted
2504 and aligned to `org-tags-column'. When called with a `C-u'
2505 prefix, all tags in the current buffer will be aligned to that
2506 column, just to make things look nice. TAGS are automatically
2507 realigned after promotion, demotion, and TODO state changes (*note
2510 Org will support tag insertion based on a _list of tags_. By
2511 default this list is constructed dynamically, containing all tags
2512 currently used in the buffer. You may also globally specify a hard list
2513 of tags with the variable `org-tag-alist'. Finally you can set the
2514 allowed tags for a given file with lines like
2516 #+TAGS: @WORK @HOME @TENNISCLUB
2517 #+TAGS: Laptop Car PC Sailboat
2519 The default support method is minibuffer completion. However,
2520 Org-mode also implements a much better method: _fast tag selection_.
2521 This method allows to select and deselect tags with a single key per
2522 tag. To function efficiently, you should assign unique keys to all
2523 tags. This can be done globally with
2525 (setq org-tag-alist '(("@WORK" . ?w) ("@HOME" . ?h) ("Laptop" . ?l)))
2527 or on a per-file basis with
2529 #+TAGS: @WORK(w) @HOME(h) @TENNISCLUB(t) Laptop(l) PC(p)
2531 You can also group together tags that are mutually exclusive. With
2534 #+TAGS: { @WORK(w) @HOME(h) @TENNISCLUB(t) } Laptop(l) PC(p)
2536 you indicate that at most one of `@WORK', `@HOME', and `@SAILBOAT'
2539 Don't forget to press `C-c C-c' with the cursor in one of these lines
2540 to activate any changes.
2542 If at least one tag has a selection key, pressing `C-c C-c' will
2543 automatically present you with a special interface, listing inherited
2544 tags, the tags of the current headline, and a list of all legal tags
2545 with corresponding keys(2). Pressing keys for the tags will add or
2546 remove them from the list of tags in the current line. Selecting a tag
2547 in a group of mutually exclusive tags will turn off any other tags from
2548 that group. <SPC> clears all tags for this line, `RET' accepts the
2549 modified set, and `C-g' aborts without installing changes. This method
2550 lets you assign tags to a headline with very few keys. With the above
2551 setup, you could clear the current tags and set `@HOME', `Laptop' and
2552 `PC' tags with just the following keys: `C-c C-c <SPC> h l p <RET>'.
2553 Switching from `@HOME' to `@WORK' would be done with `C-c C-c w <RET>'.
2555 What if you have globally defined your preferred set of tags using
2556 the variable `org-tag-alist', but would like to use a dynamic tag list
2557 in a specific file? Just add an empty TAGS option line to that file:
2561 ---------- Footnotes ----------
2563 (1) In `org-mode-alist' use `'(:startgroup)' and `'(:endgroup)',
2564 respectively. Several groups are allowed.
2566 (2) Keys will automatically assigned to tags which have no
2570 File: org, Node: Tag searches, Prev: Setting tags, Up: Tags
2575 Once a tags system has been set up, it can be used to collect related
2576 information into special lists.
2579 Create a sparse tree with all headlines matching a tags search.
2582 Create a global list of tag matches from all agenda files. *Note
2583 Matching headline tags::.
2586 Create a global list of tag matches from all agenda files, but
2587 check only TODO items and force checking subitems (see variable
2588 `org-tags-match-list-sublevels').
2590 A tags search string can use Boolean operators `&' for AND and `|'
2591 for OR. `&' binds more strongly than `|'. Parenthesis are currently
2592 not implemented. A tag may also be preceded by `-', to select against
2593 it, and `+' is syntactic sugar for positive selection. The AND
2594 operator `&' is optional when `+' or `-' is present. For example,
2595 `+WORK-BOSS' would select all headlines that are tagged `:WORK:', but
2596 discard those also tagged `:BOSS:'. The search string `WORK|LAPTOP'
2597 selects all lines tagged `:WORK:' or `:LAPTOP:'. The string
2598 `WORK|LAPTOP&NIGHT' requires that the `:LAPTOP:' lines are also tagged
2602 File: org, Node: Agenda views, Next: Embedded LaTeX, Prev: Tags, Up: Top
2607 Due to the way Org-mode works, TODO items, time-stamped items, and
2608 tagged headlines can be scattered throughout a file or even a number of
2609 files. To get an overview over open action items, or over events that
2610 are important for a particular date, this information must be collected,
2611 sorted and displayed in an organized way.
2613 Org-mode can select items based on various criteria, and display them
2614 in a separate buffer. Three different views are provided:
2616 * an _agenda_ that is like a calendar and shows information for
2619 * a _TODO list_ that covers all unfinished action items, and
2621 * a _tags view_ that shows information based on the tags associated
2622 with headlines in the outline tree.
2624 The extracted information is displayed in a special _agenda buffer_.
2625 This buffer is read-only, but provides commands to visit the
2626 corresponding locations in the original Org-mode files, and even to
2627 edit these files remotely.
2631 * Agenda files:: Files being searched for agenda information
2632 * Agenda dispatcher:: Keyboard access to agenda views
2633 * Weekly/Daily agenda:: The calendar page with current tasks
2634 * Global TODO list:: All unfinished action items
2635 * Matching headline tags:: Structured information with fine-tuned search
2636 * Timeline:: Time-sorted view for single file
2637 * Agenda commands:: Remote editing of org trees
2640 File: org, Node: Agenda files, Next: Agenda dispatcher, Prev: Agenda views, Up: Agenda views
2645 The information to be shown is collected from all _agenda files_, the
2646 files listed in the variable `org-agenda-files'(1). Thus even if you
2647 only work with a single Org-mode file, this file should be put into
2648 that list(2). You can customize `org-agenda-files', but the easiest
2649 way to maintain it is through the following commands
2652 Add current file to the list of agenda files. The file is added to
2653 the front of the list. If it was already in the list, it is moved
2654 to the front. With prefix arg, file is added/moved to the end.
2657 Remove current file from the list of agenda files.
2660 Cycle through agenda file list, visiting one file after the other.
2662 The Org menu contains the current list of files and can be used to
2665 ---------- Footnotes ----------
2667 (1) If the value of that variable is not a list, but a single file
2668 name, then the list of agenda files will be maintained in that external
2671 (2) When using the dispatcher pressing `1' before selecting a
2672 command will actually limit the command to the current file, and ignore
2673 `org-agenda-files' until the next dispatcher command.
2676 File: org, Node: Agenda dispatcher, Next: Weekly/Daily agenda, Prev: Agenda files, Up: Agenda views
2678 8.2 The agenda dispatcher
2679 =========================
2681 The views are created through a dispatcher that should be bound to a
2682 global key, for example `C-c a' (*note Installation::). In the
2683 following we will assume that `C-c a' is indeed how the dispatcher is
2684 accessed and list keyboard access to commands accordingly. After
2685 pressing `C-c a', an additional letter is required to execute a
2686 command. The dispatcher offers the following default commands:
2688 Create the calendar-like agenda (*note Weekly/Daily agenda::).
2691 Create a list of all TODO items (*note Global TODO list::).
2694 Create a list of headlines matching a TAGS expression (*note
2695 Matching headline tags::).
2697 You can also define custom commands that will be accessible through
2698 the dispatcher, just like the default commands. Custom commands are
2699 global searches for tags and specific TODO keywords, or a variety of
2700 sparse tree creating commands (*note Sparse trees::). As sparse trees
2701 are only defined for a single org-mode file, these latter commands act
2702 on the current buffer instead of the list of agenda files.
2704 Custom commands are configured in the variable
2705 `org-agenda-custom-commands'. You can customize this variable, for
2706 example by pressing `C-c a C'. You can also directly set it with Emacs
2707 Lisp in `.emacs'. For example:
2709 (setq org-agenda-custom-commands
2710 '(("w" todo "WAITING")
2711 ("u" tags "+BOSS-URGENT")
2712 ("U" tags-tree "+BOSS-URGENT")
2713 ("f" occur-tree "\\<FIXME\\>")))
2715 will define `C-c a w' as a global search for TODO entries with
2716 `WAITING' as the TODO keyword, `C-c a u' as a global tags search for
2717 headlines marked `:BOSS:' but not `:URGENT:', `C-c a U' to do the same
2718 search but only in the current buffer and display the result as a
2719 sparse tree, and `C-c a f' to create a sparse tree with all entries
2720 containing the word `FIXME'. For more information, look at the
2721 documentation string of the variable `org-agenda-custom-commands'.
2724 File: org, Node: Weekly/Daily agenda, Next: Global TODO list, Prev: Agenda dispatcher, Up: Agenda views
2726 8.3 The weekly/daily agenda
2727 ===========================
2729 The purpose of the weekly/daily _agenda_ is to act like a page of a
2730 paper agenda, showing all the tasks for the current week or day.
2733 Compile an agenda for the current week from a list of org files.
2734 The agenda shows the entries for each day. With a `C-u' prefix (or
2735 when the variable `org-agenda-include-all-todo' is `t'), all
2736 unfinished TODO items (including those without a date) are also
2737 listed at the beginning of the buffer, before the first date.
2739 Remote editing from the agenda buffer means, for example, that you
2740 can change the dates of deadlines and appointments from the agenda
2741 buffer. The commands available in the Agenda buffer are listed in
2742 *Note Agenda commands::.
2746 * Categories:: Not all tasks are equal
2747 * Time-of-day specifications:: How the agenda knows the time
2748 * Calendar/Diary integration:: Integrating Anniversaries and more
2749 * Sorting of agenda items:: The order of things
2752 File: org, Node: Categories, Next: Time-of-day specifications, Prev: Weekly/Daily agenda, Up: Weekly/Daily agenda
2757 In the agenda buffer, each entry is preceded by a _category_, which is
2758 derived from the file name. The category can also be set with a
2759 special line anywhere in the buffer, looking like this:
2763 If there are several such lines in a file, each specifies the
2764 category for the text below it (but the first category also applies to
2765 any text before the first CATEGORY line). The display in the agenda
2766 buffer looks best if the category is not longer than 10 characters.
2769 File: org, Node: Time-of-day specifications, Next: Calendar/Diary integration, Prev: Categories, Up: Weekly/Daily agenda
2771 8.3.2 Time-of-Day Specifications
2772 --------------------------------
2774 Org-mode checks each agenda item for a time-of-day specification. The
2775 time can be part of the time stamp that triggered inclusion into the
2776 agenda, for example as in `<2005-05-10 Tue 19:00>'. Time ranges can be
2777 specified with two time stamps, like
2778 `<2005-05-10 Tue 20:30>--<2005-05-10 Tue 22:15>'.
2780 In the headline of the entry itself, a time(range) may also appear as
2781 plain text (like `12:45' or a `8:30-1pm'. If the agenda integrates the
2782 Emacs diary (*note Calendar/Diary integration::), time specifications
2783 in diary entries are recognized as well.
2785 For agenda display, Org-mode extracts the time and displays it in a
2786 standard 24 hour format as part of the prefix. The example times in
2787 the previous paragraphs would end up in the agenda like this:
2789 8:30-13:00 Arthur Dent lies in front of the bulldozer
2790 12:45...... Ford Prefect arrives and takes Arthur to the pub
2791 19:00...... The Vogon reads his poem
2792 20:30-22:15 Marwin escorts the Hitchhikers to the bridge
2794 If the agenda is in single-day mode, or for the display of today, the
2795 timed entries are embedded in a time grid, like
2797 8:00...... ------------------
2798 8:30-13:00 Arthur Dent lies in front of the bulldozer
2799 10:00...... ------------------
2800 12:00...... ------------------
2801 12:45...... Ford Prefect arrives and takes Arthur to the pub
2802 14:00...... ------------------
2803 16:00...... ------------------
2804 18:00...... ------------------
2805 19:00...... The Vogon reads his poem
2806 20:00...... ------------------
2807 20:30-22:15 Marwin escorts the Hitchhikers to the bridge
2809 The time grid can be turned on and off with the variable
2810 `org-agenda-use-time-grid', and can be configured with
2811 `org-agenda-time-grid'.
2814 File: org, Node: Calendar/Diary integration, Next: Sorting of agenda items, Prev: Time-of-day specifications, Up: Weekly/Daily agenda
2816 8.3.3 Calendar/Diary integration
2817 --------------------------------
2819 Emacs contains the calendar and diary by Edward M. Reingold. The
2820 calendar displays a three-month calendar with holidays from different
2821 countries and cultures. The diary allows you to keep track of
2822 anniversaries, lunar phases, sunrise/set, recurrent appointments
2823 (weekly, monthly) and more. In this way, it is quite complementary to
2824 Org-mode. It can be very useful to combine output from Org-mode with
2827 In order to include entries from the Emacs diary into Org-mode's
2828 agenda, you only need to customize the variable
2830 (setq org-agenda-include-diary t)
2832 After that, everything will happen automatically. All diary entries
2833 including holidays, anniversaries etc will be included in the agenda
2834 buffer created by Org-mode. <SPC>, <TAB>, and <RET> can be used from
2835 the agenda buffer to jump to the diary file in order to edit existing
2836 diary entries. The `i' command to insert new entries for the current
2837 date works in the agenda buffer, as well as the commands `S', `M', and
2838 `C' to display Sunrise/Sunset times, show lunar phases and to convert
2839 to other calendars, respectively. `c' can be used to switch back and
2840 forth between calendar and agenda.
2843 File: org, Node: Sorting of agenda items, Prev: Calendar/Diary integration, Up: Weekly/Daily agenda
2845 8.3.4 Sorting of agenda items
2846 -----------------------------
2848 The entries for each day are sorted. The default order is to first
2849 collect all items containing an explicit time-of-day specification.
2850 These entries will be shown at the beginning of the list, as a
2851 _schedule_ for the day. After that, items remain grouped in
2852 categories, in the sequence given by `org-agenda-files'. Within each
2853 category, items are sorted by priority (*note Priorities::).
2855 The priority is a numerical quantity composed of the base priority
2856 (2000 for priority `A', 1000 for `B', and 0 for `C'), plus additional
2857 increments for overdue scheduled or deadline items.
2859 Sorting can be customized using the variable
2860 `org-agenda-sorting-strategy'.
2863 File: org, Node: Global TODO list, Next: Matching headline tags, Prev: Weekly/Daily agenda, Up: Agenda views
2865 8.4 The global TODO list
2866 ========================
2868 The global TODO list contains all unfinished TODO items, formatted and
2869 collected into a single place.
2872 Show the global TODO list. This collects the TODO items from all
2873 agenda files (*note Agenda views::) into a single buffer. The
2874 buffer is in `agenda-mode', so there are commands to examine and
2875 manipulate the TODO entries directly from that buffer (*note
2879 Like the above, but allows selection of a specific TODO keyword.
2880 You can also do this by specifying a prefix argument to `C-c a t'.
2881 With a `C-u' prefix you are prompted for a keyword. With a
2882 numeric prefix, the Nth keyword in `org-todo-keywords' is selected. The
2883 `r' key in the agenda buffer regenerates it, and you can give a
2884 prefix argument to this command to change the selected TODO
2885 keyword, for example `3 r'. If you often need a search for a
2886 specific keyword, define a custom command for it (*note Agenda
2889 Remote editing of TODO items means that you can change the state of a
2890 TODO entry with a single key press. The commands available in the TODO
2891 list are described in *Note Agenda commands::.
2893 Nomally the global todo list simply shows all headlines with TODO
2894 keywords. This list can become very long. There are two ways to keep
2896 - Some people view a TODO item that has been _scheduled_ for
2897 execution (*note Time stamps::) as no longer _open_. Configure the
2898 variable `org-agenda-todo-ignore-scheduled' to exclude scheduled
2899 items from the global TODO list.
2901 - TODO items may have sublevels to break up the task into subtasks.
2902 In such cases it may be enough to list only the highest level TODO
2903 headline and omit the sublevels from the global list. Configure
2904 the variable `org-agenda-todo-list-sublevels' to get this behavior.
2907 File: org, Node: Matching headline tags, Next: Timeline, Prev: Global TODO list, Up: Agenda views
2909 8.5 Matching headline tags
2910 ==========================
2912 If headlines in the agenda files are marked with _tags_ (*note Tags::),
2913 you can select headlines based on the tags that apply to them and
2914 collect them into an agenda buffer.
2917 Produce a list of all headlines that match a given set of tags.
2918 The command prompts for a selection criterion, which is a boolean
2919 logic expression with tags, like `+WORK+URGENT-WITHBOSS' or
2920 `WORK|HOME' (*note Tags::). If you often need a specific search,
2921 define a custom command for it (*note Agenda dispatcher::).
2924 Like `C-c a m', but only select headlines that are also TODO items
2925 and force checking subitems (see variable
2926 `org-tags-match-list-sublevels'.
2928 The commands available in the tags list are described in *Note
2932 File: org, Node: Timeline, Next: Agenda commands, Prev: Matching headline tags, Up: Agenda views
2934 8.6 Timeline for a single file
2935 ==============================
2937 The timeline is not really an agenda view, because it only summarizes
2938 items from a single Org-mode file. But it also uses the agenda buffer
2939 and provides similar commands, so we discuss it here. The timeline
2940 shows all time-stamped items in a single Org-mode file (or the selected
2941 part of it), in a _time-sorted view_. The main purpose of this command
2942 is to give an overview over events in a project.
2945 Show a time-sorted view of the org file, with all time-stamped
2946 items. When called with a `C-u' prefix, all unfinished TODO
2947 entries (scheduled or not) are also listed under the current date.
2949 The commands available in the timeline buffer are listed in *Note
2953 File: org, Node: Agenda commands, Prev: Timeline, Up: Agenda views
2955 8.7 Commands in the agenda buffer
2956 =================================
2958 Entries in the agenda buffer are linked back to the org file or diary
2959 file where they originate. You are not allowed to edit the agenda
2960 buffer itself, but commands are provided to show and jump to the
2961 original entry location, and to edit the org-files "remotely" from the
2962 agenda buffer. In this way, all information is stored only once,
2963 removing the risk that your agenda and note files may diverge.
2965 Some commands can be executed with mouse clicks on agenda lines. For
2966 the other commands, the cursor needs to be in the desired line.
2972 Next line (same as <up>).
2975 Previous line (same as <down>).
2982 Display the original location of the item in another window.
2985 Display original location and recenter that window.
2990 Go to the original location of the item in another window. Under
2991 Emacs 22, `mouse-1' will also works for this.
2994 Go to the original location of the item and delete other windows.
2997 Toggle Follow mode. In Follow mode, as you move the cursor through
2998 the agenda buffer, the other window always shows the corresponding
2999 location in the org file. The initial setting for this mode in new
3000 agenda buffers can be set with the variable
3001 `org-agenda-start-with-follow-mode'.
3004 Toggle Logbook mode. In Logbook mode, entries that where marked
3005 DONE while logging was on (variable `org-log-done') are shown in
3006 the agenda, as are entries that have been clocked on that day.
3012 Delete other windows.
3015 Switch to weekly view (7 days displayed together).
3018 Switch to daily view (just one day displayed).
3021 Toggle the inclusion of diary entries. See *Note Calendar/Diary
3025 Toggle the time grid on and off. See also the variables
3026 `org-agenda-use-time-grid' and `org-agenda-time-grid'.
3029 Recreate the agenda buffer, for example to reflect the changes
3030 after modification of the time stamps of items with S-<left> and
3031 S-<right>. When the buffer is the global todo list, a prefix
3032 argument is interpreted to create a selective list for a specific
3036 Save all Org-mode buffers in the current Emacs session.
3039 Display the following `org-agenda-ndays' days. For example, if
3040 the display covers a week, switch to the following week. With
3041 prefix arg, go forward that many times `org-agenda-ndays' days.
3044 Display the previous dates.
3056 Change the TODO state of the item, both in the agenda and in the
3060 Show all tags associated with the current item. Because of
3061 inheritance, this may be more than the tags listed in the line
3065 Set tags for the current headline.
3068 Toggle the ARCHIVE tag for the current headline.
3071 Set the priority for the current item. Org-mode prompts for the
3072 priority character. If you reply with <SPC>, the priority cookie
3073 is removed from the entry.
3076 Display weighted priority of current item.
3080 Increase the priority of the current item. The priority is
3081 changed in the original buffer, but the agenda is not resorted.
3082 Use the `r' key for this.
3086 Decrease the priority of the current item.
3092 Set a deadline for this item.
3095 Change the time stamp associated with the current line by one day
3096 into the future. With prefix argument, change it by that many
3097 days. For example, `3 6 5 S-<right>' will change it by a year.
3098 The stamp is changed in the original org file, but the change is
3099 not directly reflected in the agenda buffer. Use the `r' key to
3103 Change the time stamp associated with the current line by one day
3107 Change the time stamp associated with the current line to today.
3108 The key `>' has been chosen, because it is the same as `S-.' on my
3112 Start the clock on the current item. If a clock is running
3113 already, it is stopped first.
3116 Stop the previously started clock.
3119 Cancel the currently running clock.
3125 Open the Emacs calendar and move to the date at the agenda cursor.
3128 When in the calendar, compute and show the Org-mode agenda for the
3132 Insert a new entry into the diary. Prompts for the type of entry
3133 (day, weekly, monthly, yearly, anniversary, cyclic) and creates a
3134 new entry in the diary, just as `i d' etc. would do in the
3135 calendar. The date is taken from the cursor position.
3138 Show the phases of the moon for the three months around current
3142 Show sunrise and sunset times. The geographical location must be
3143 set with calendar variables, see documentation of the Emacs
3147 Convert the date at cursor into many other cultural and historic
3151 Show holidays for three month around the cursor date.
3154 Export a single iCalendar file containing entries from all agenda
3161 Quit agenda, remove the agenda buffer.
3164 Exit agenda, remove the agenda buffer and all buffers loaded by
3165 Emacs for the compilation of the agenda. Buffers created by the
3166 user to visit org files will not be removed.
3170 File: org, Node: Embedded LaTeX, Next: Exporting, Prev: Agenda views, Up: Top
3175 Plain ASCII is normally sufficient for almost all note taking. One
3176 exception, however, are scientific notes which need to be able to
3177 contain mathematical symbols and the occasional formula. LaTeX(1) is
3178 widely used to typeset scientific documents. Org-mode supports
3179 embedding LaTeX code into its files, because many academics are used to
3180 read LaTeX source code, and because it can be readily processed into
3181 images for HTML production.
3183 It is not necessary to mark LaTeX macros and code in any special way.
3184 If you observe a few conventions, Org-mode knows how to find it and what
3189 * Math symbols:: TeX macros for symbols and Greek letters
3190 * Subscripts and Superscripts:: Simple syntax for raising/lowering text
3191 * LaTeX fragments:: Complex formulas made easy
3192 * Processing LaTeX fragments:: Previewing LaTeX processing
3193 * CDLaTeX mode:: Speed up entering of formulas
3195 ---------- Footnotes ----------
3197 (1) LaTeX is a macro system based on Donald E. Knuth's TeX system.
3198 Many of the features described here as "LaTeX" are really from TeX, but
3199 for simplicity I am blurring this distinction.
3202 File: org, Node: Math symbols, Next: Subscripts and Superscripts, Prev: Embedded LaTeX, Up: Embedded LaTeX
3207 You can use LaTeX macros to insert special symbols like `\alpha' to
3208 indicate the Greek letter, or `\to' to indicate an arrow. Completion
3209 for these macros is available, just type `\' and maybe a few letters,
3210 and press `M-<TAB>' to see possible completions. Unlike LaTeX code,
3211 Org-mode allows these macros to be present without surrounding math
3212 delimiters, for example:
3214 Angles are written as Greek letters \alpha, \beta and \gamma.
3216 During HTML export (*note HTML export::), these symbols are
3217 translated into the proper syntax for HTML, for the above examples this
3218 is `α' and `→', respectively.
3221 File: org, Node: Subscripts and Superscripts, Next: LaTeX fragments, Prev: Math symbols, Up: Embedded LaTeX
3223 9.2 Subscripts and Superscripts
3224 ===============================
3226 Just like in LaTeX, `^' and `_' are used to indicate super- and
3227 subscripts. Again, these can be used without embedding them in
3228 math-mode delimiters. To increase the readability of ASCII text, it is
3229 not necessary (but OK) to surround multi-character sub- and superscripts
3230 with curly braces. For example
3232 The mass if the sun is M_sun = 1.989 x 10^30 kg. The radius of
3233 the sun is R_{sun} = 6.96 x 10^8 m.
3235 To avoid interpretation as raised or lowered text, you can quote `^'
3236 and `_' with a backslash: `\_' and `\^'.
3238 During HTML export (*note HTML export::), subscript and superscripts
3239 are surrounded with `<sub>' and `<sup>' tags, respectively.
3242 File: org, Node: LaTeX fragments, Next: Processing LaTeX fragments, Prev: Subscripts and Superscripts, Up: Embedded LaTeX
3247 With symbols, sub- and superscripts, HTML is pretty much at its end when
3248 it comes to representing mathematical formulas. More complex
3249 expressions need a dedicated formula processor. To this end, Org-mode
3250 can contain arbitrary LaTeX fragments. It provides commands to preview
3251 the typeset result of these fragments, and upon export to HTML, all
3252 fragments will be converted to images and inlined into the HTML
3253 document. For this to work you need to be on a system with a working
3254 LaTeX installation. You also need the `dvipng' program, available at
3255 `http://sourceforge.net/projects/dvipng/'.
3257 LaTeX fragments don't need any special marking at all. The following
3258 snippets will be identified as LaTeX source code:
3259 * Environments of any kind. The only requirement is that the
3260 `\begin' statement appears on a new line, preceded by only
3263 * Text within the usual LaTeX math delimiters. To avoid conflicts
3264 with currency specifications, single `$' characters are only
3265 recognized as math delimiters if the enclosed text contains at
3266 most two line breaks, is directly attached to the `$' characters
3267 with no whitespace in between, and if the closing `$' is followed
3268 by whitespace or punctuation. For the other delimiters, there is
3269 no such restriction, so when in doubt, use `\(...\)' as inline
3274 \begin{equation} % arbitrary environments,
3275 x=\sqrt{b} % even tables, figures
3276 \end{equation} % etc
3278 If $a^2=b$ and \( b=2 \), then the solution must be
3279 either $$ a=+\sqrt{2} $$ or \[ a=-\sqrt{2} \].
3281 If you need any of the delimiter ASCII sequences for other purposes, you
3282 can configure the option `org-format-latex-options' to deselect the
3283 ones you do not wish to have interpreted by the LaTeX converter.
3286 File: org, Node: Processing LaTeX fragments, Next: CDLaTeX mode, Prev: LaTeX fragments, Up: Embedded LaTeX
3288 9.4 Processing LaTeX fragments
3289 ==============================
3291 LaTeX fragments can be processed to produce a preview images of the
3292 typeset expressions:
3295 Produce a preview image of the LaTeX fragment at point and overlay
3296 it over the source code. If there is no fragment at point,
3297 process all fragments in the current entry (between two
3298 headlines). When called with a prefix argument, process the
3299 entire subtree. When called with two prefix arguments, or when
3300 the cursor is before the first headline, process the entire buffer.
3303 Remove the overlay preview images.
3305 During HTML export (*note HTML export::), all LaTeX fragments are
3306 converted into images and inlined into the document if the following
3309 (setq org-export-with-LaTeX-fragments t)
3312 File: org, Node: CDLaTeX mode, Prev: Processing LaTeX fragments, Up: Embedded LaTeX
3314 9.5 Using CDLaTeX to enter math
3315 ===============================
3317 CDLaTeX-mode is a minor mode that is normally used in combination with a
3318 major LaTeX mode like AUCTeX in order to speed-up insertion of
3319 environments and math templates. Inside Org-mode, you can make use of
3320 some of the features of cdlatex-mode. You need to install `cdlatex.el'
3321 and `texmathp.el' (the latter comes also with AUCTeX) from
3322 `http://www.astro.uva.nl/~dominik/Tools/cdlatex'. Don't turn
3323 cdlatex-mode itself under Org-mode, but use the light version
3324 `org-cdlatex-mode' that comes as part of Org-mode. Turn it on for the
3325 current buffer with `M-x org-cdlatex-mode', or for all Org-mode files
3328 (add-hook 'org-mode-hook 'turn-on-org-cdlatex)
3330 When this mode is enabled, the following features are present (for
3331 more details see the documentation of cdlatex-mode):
3332 * Environment templates can be inserted with `C-c {'.
3334 * The <TAB> key will do template expansion if the cursor is inside a
3335 LaTeX fragment(1). For example, <TAB> will expand `fr' to
3336 `\frac{}{}' and position the cursor correctly inside the first
3337 brace. Another <TAB> will get you into the second brace. Even
3338 outside fragments, <TAB> will expand environment abbreviations at
3339 the beginning of a line. For example, if you write `equ' at the
3340 beginning of a line and press <TAB>, this abbreviation will be
3341 expanded to an `equation' environment. To get a list of all
3342 abbreviations, type `M-x cdlatex-command-help'.
3344 * Pressing `_' and `^' inside a LaTeX fragment will insert these
3345 characters together with a pair of braces. If you use <TAB> to
3346 move out of the braces, and if the braces surround only a single
3347 character or macro, they are removed again (depending on the
3348 variable `cdlatex-simplify-sub-super-scripts').
3350 * Pressing the backquote ``' followed by a character inserts math
3351 macros, also outside LaTeX fragments. If you wait more than 1.5
3352 seconds after the backquote, a help window will pop up.
3354 * Pressing the normal quote `'' followed by another character
3355 modifies the symbol before point with an accent or a font. If you
3356 wait more than 1.5 seconds after the backquote, a help window will
3357 pop up. Character modification will work only inside LaTeX
3358 fragments, outside the quote is normal.
3360 ---------- Footnotes ----------
3362 (1) Org-mode has a method to test if the cursor is inside such a
3363 fragment, see the documentation of the function
3364 `org-inside-LaTeX-fragment-p'.
3367 File: org, Node: Exporting, Next: Publishing, Prev: Embedded LaTeX, Up: Top
3372 Org-mode documents can be exported into a variety of other formats. For
3373 printing and sharing of notes, ASCII export produces a readable and
3374 simple version of an Org-mode file. HTML export allows you to publish a
3375 notes file on the web, while the XOXO format provides a solid base for
3376 exchange with a broad range of other applications. To incorporate
3377 entries with associated times like deadlines or appointments into a
3378 desktop calendar program like iCal, Org-mode can also produce extracts
3379 in the iCalendar format. Currently Org-mode only supports export, not
3380 import of these different formats.
3382 When exporting, Org-mode uses special conventions to enrich the
3383 output produced. *Note Text interpretation::, for more details.
3386 Dispatcher for export and publishing commands. Displays a
3387 help-window listing the additional key(s) needed to launch an
3388 export or publishing command.
3392 * ASCII export:: Exporting to plain ASCII
3393 * HTML export:: Exporting to HTML
3394 * XOXO export:: Exporting to XOXO
3395 * iCalendar export:: Exporting in iCalendar format
3396 * Text interpretation:: How the exporter looks at the file
3399 File: org, Node: ASCII export, Next: HTML export, Prev: Exporting, Up: Exporting
3404 ASCII export produces a simple and very readable version of an Org-mode
3408 Export as ASCII file. If there is an active region, only the
3409 region will be exported. For an org file `myfile.org', the ASCII
3410 file will be `myfile.txt'. The file will be overwritten without
3414 Export only the visible part of the document.
3416 In the exported version, the first 3 outline levels will become
3417 headlines, defining a general document structure. Additional levels
3418 will be exported as itemized lists. If you want that transition to
3419 occur at a different level, specify it with a prefix argument. For
3424 creates only top level headlines and does the rest as items. When
3425 headlines are converted to items, the indentation of the text following
3426 the headline is changed to fit nicely under the item. This is done with
3427 the assumption that the first bodyline indicates the base indentation of
3428 the body text. Any indentation larger than this is adjusted to preserve
3429 the layout relative to the first line. Should there be lines with less
3430 indentation than the first, these are left alone.
3433 File: org, Node: HTML export, Next: XOXO export, Prev: ASCII export, Up: Exporting
3438 Org-mode contains an HTML (XHTML 1.0 strict) exporter with extensive
3439 HTML formatting, in ways similar to John Grubers _markdown_ language,
3440 but with additional support for tables.
3443 Export as HTML file `myfile.html'.
3446 Export as HTML file and open it with a browser.
3451 Export only the visible part of the document.
3453 In the exported version, the first 3 outline levels will become
3454 headlines, defining a general document structure. Additional levels
3455 will be exported as itemized lists. If you want that transition to
3456 occur at a different level, specify it with a prefix argument. For
3461 creates two levels of headings and does the rest as items.
3463 If you want to include HTML tags which should be interpreted as such,
3464 mark them with `@' as in `@<b>bold text@</b>'. Plain `<' and `>' are
3465 always transformed to `<' and `>' in HTML export.
3467 Internal links (*note Internal links::) will continue to work in HTML
3468 files only if they match a dedicated `<<target>>'. Automatic links
3469 created by radio targets (*note Radio targets::) will also work in the
3470 HTML file. Links to external files will still work if the HTML file is
3471 in the same directory as the Org-mode file. Links to other `.org'
3472 files will be translated into HTML links under the assumption that an
3473 HTML version also exists of the linked file. For information related to
3474 linking files while publishing them to a publishing directory see *Note
3477 You can also give style information for the exported file. The HTML
3478 exporter assigns the following CSS classes to appropriate parts of the
3479 document - your style specifications may change these:
3481 .done the DONE keyword
3482 .timestamp time stamp
3483 .timestamp-kwd keyword associated with a time stamp, like SCHEDULED
3484 .tag tag in a headline
3485 .target target for links
3487 The default style specification can be configured through the option
3488 `org-export-html-style'. If you want to use a file-local style, you
3489 may use file variables, best wrapped into a COMMENT section at the end
3490 of the outline tree. For example:
3492 * COMMENT HTML style specifications
3495 # org-export-html-style: " <style type=\"text/css\">
3496 # p {font-weight: normal; color: gray; }
3497 # h1 {color: black; }
3501 Remember to execute `M-x normal-mode' after changing this to make
3502 the new style visible to Emacs. This command restarts org-mode for the
3503 current buffer and forces Emacs to re-evaluate the local variables
3504 section in the buffer.
3507 File: org, Node: XOXO export, Next: iCalendar export, Prev: HTML export, Up: Exporting
3512 Org-mode contains an exporter that produces XOXO-style output.
3513 Currently, this exporter only handles the general outline structure and
3514 does not interpret any additional Org-mode features.
3517 Export as XOXO file `myfile.html'.
3520 Export only the visible part of the document.
3523 File: org, Node: iCalendar export, Next: Text interpretation, Prev: XOXO export, Up: Exporting
3525 10.4 iCalendar export
3526 =====================
3528 Some people like to use Org-mode for keeping track of projects, but
3529 still prefer a standard calendar application for anniversaries and
3530 appointments. In this case it can be useful to have deadlines and
3531 other time-stamped items in Org-mode files show up in the calendar
3532 application. Org-mode can export calendar information in the standard
3536 Create iCalendar entries for the current file and store them in
3537 the same directory, using a file extension `.ics'.
3540 Like `C-c C-e i', but do this for all files in `org-agenda-files'.
3541 For each of these files, a separate iCalendar file will be
3545 Create a single large iCalendar file from all files in
3546 `org-agenda-files' and write it to the file given by
3547 `org-combined-agenda-icalendar-file'.
3549 How this calendar is best read and updated, depends on the
3550 application you are using. For example, when using iCal under Apple
3551 MacOS X, you could create a new calendar `OrgMode' (the default name
3552 for the calendar created by `C-c C-e c', see the variables
3553 `org-icalendar-combined-name' and
3554 `org-combined-agenda-icalendar-file'). Then set Org-mode to overwrite
3555 the corresponding file `~/Library/Calendars/OrgMode.ics'. You may even
3556 use AppleScript to make iCal re-read the calendar files each time a new
3557 version of `OrgMode.ics' is produced. Here is the setup needed for
3560 (setq org-combined-agenda-icalendar-file
3561 "~/Library/Calendars/OrgMode.ics")
3562 (add-hook 'org-after-save-iCalendar-file-hook
3565 "osascript -e 'tell application \"iCal\" to reload calendars'")))
3568 File: org, Node: Text interpretation, Prev: iCalendar export, Up: Exporting
3570 10.5 Text interpretation by the exporter
3571 ========================================
3573 The exporter backends interpret additional structure in the Org-mode
3574 file in order to produce better output.
3578 * Comment lines:: Some lines will not be exported
3579 * Enhancing text:: Subscripts, symbols and more
3580 * Export options:: How to influence the export settings
3583 File: org, Node: Comment lines, Next: Enhancing text, Prev: Text interpretation, Up: Text interpretation
3585 10.5.1 Comment lines
3586 --------------------
3588 Lines starting with `#' in column zero are treated as comments and will
3589 never be exported. Also entire subtrees starting with the word
3590 `COMMENT' will never be exported. Finally, any text before the first
3591 headline will not be exported either.
3594 Toggle the COMMENT keyword at the beginning of an entry.
3597 File: org, Node: Enhancing text, Next: Export options, Prev: Comment lines, Up: Text interpretation
3599 10.5.2 Enhancing text for export
3600 --------------------------------
3602 Some of the export backends of Org-mode allow for sophisticated text
3603 formatting, this is true in particular for the HTML backend. Org-mode
3604 has a number of typing conventions that allow to produce a richly
3607 * Plain lists `-', `*' or `+' as bullet, or with `1.' or `2)' as
3608 enumerator will be recognized and transformed if the backend
3609 supports lists. See *Note Plain lists::.
3611 * You can make words *bold*, /italic/, _underlined_, `=code=', and
3614 * Many TeX macros and entire LaTeX fragments are converted into HTML
3615 entities or images (*note Embedded LaTeX::).
3617 * Tables are transformed into native tables under the exporter, if
3618 the export backend supports this. Data fields before the first
3619 horizontal separator line will be formatted as table header fields.
3621 * If a headline starts with the word `QUOTE', the text below the
3622 headline will be typeset as fixed-width, to allow quoting of
3623 computer codes etc. Lines starting with `:' are also typeset in
3626 Toggle fixed-width for entry (QUOTE) or region, see below.
3628 * A double backslash _at the end of a line_ enforces a line break at
3631 If these conversions conflict with your habits of typing ASCII text,
3632 they can all be turned off with corresponding variables (see the
3633 customization group `org-export-general', and the following section
3634 which explains how to set export options with special lines in a buffer.
3637 File: org, Node: Export options, Prev: Enhancing text, Up: Text interpretation
3639 10.5.3 Export options
3640 ---------------------
3642 The exporter recognizes special lines in the buffer which provide
3643 additional information. These lines may be put anywhere in the file.
3644 The whole set of lines can be inserted into the buffer with `C-c C-e
3645 t'. For individual lines, a good way to make sure the keyword is
3646 correct is to type `#+' and then use `M-<TAB>' completion (*note
3650 Insert template with export options, see example below.
3652 #+TITLE: the title to be shown (default is the buffer name)
3653 #+AUTHOR: the author (default taken from `user-full-name')
3654 #+EMAIL: his/her email address (default from `user-mail-address')
3655 #+LANGUAGE: language for HTML, e.g. `en' (`org-export-default-language')
3656 #+TEXT: Some descriptive text to be inserted at the beginning.
3657 #+TEXT: Several lines may be given.
3658 #+OPTIONS: H:2 num:t toc:t \n:nil @:t ::t |:t ^:t *:nil TeX:t LaTeX:t
3660 The OPTIONS line is a compact form to specify export settings. Here
3662 H: set the number of headline levels for export
3663 num: turn on/off section-numbers
3664 toc: turn on/off table of contents
3665 \n: turn on/off linebreak-preservation
3666 @: turn on/off quoted HTML tags
3667 :: turn on/off fixed-width sections
3668 |: turn on/off tables
3669 ^: turn on/off TeX-like syntax for sub- and superscripts.
3670 *: turn on/off emphasized text (bold, italic, underlined)
3671 TeX: turn on/off simple TeX macros in plain text
3672 LaTeX: turn on/off LaTeX fragments
3675 File: org, Node: Publishing, Next: Miscellaneous, Prev: Exporting, Up: Top
3680 Org-mode includes(1) a publishing management system that allows you to
3681 configure automatic HTML conversion of _projects_ composed of
3682 interlinked org files. This system is called _org-publish_. You can
3683 also configure org-publish to automatically upload your exported HTML
3684 pages and related attachments, such as images and source code files, to
3685 a web server. Org-publish turns org-mode into a web-site authoring
3688 Org-publish has been contributed to Org-mode by David O'Toole.
3692 * Configuration:: Defining projects
3693 * Sample configuration:: Example projects
3694 * Triggering publication:: Publication commands
3696 ---------- Footnotes ----------
3698 (1) `org-publish.el' is not yet part of Emacs, so if you are using
3699 `org.el' as it comes with Emacs, you need to download this file
3700 separately. Also make sure org.el is at least version 4.27.
3703 File: org, Node: Configuration, Next: Sample configuration, Prev: Publishing, Up: Publishing
3708 Publishing needs significant configuration to specify files, destination
3709 and many other properties of a project.
3713 * Project alist:: The central configuration variable
3714 * Sources and destinations:: From here to there
3715 * Selecting files:: What files are part of the project?
3716 * Publishing action:: Setting the function doing the publishing
3717 * Publishing options:: Tweaking HTML export
3718 * Publishing links:: Which links keep working after publishing?
3719 * Project page index:: Publishing a list of project files
3722 File: org, Node: Project alist, Next: Sources and destinations, Prev: Configuration, Up: Configuration
3724 11.1.1 The variable `org-publish-project-alist'
3725 -----------------------------------------------
3727 Org-publish is configured almost entirely through setting the value of
3728 one variable, called `org-publish-project-alist'. Each element of the
3729 list configures one project, and may be in one of the two following
3732 ("project-name" :property value :property value ...)
3736 ("project-name" :components ("project-name" "project-name" ...))
3738 In both cases, projects are configured by specifying property values.
3739 A project defines the set of files that will be published, as well as
3740 the publishing configuration to use when publishing those files. When
3741 a project takes the second form listed above, the individual members of
3742 the "components" property are taken to be components of the project,
3743 which group together files requiring different publishing options. When
3744 you publish such a "meta-project" all the components will also publish.
3747 File: org, Node: Sources and destinations, Next: Selecting files, Prev: Project alist, Up: Configuration
3749 11.1.2 Sources and destinations for files
3750 -----------------------------------------
3752 Most properties are optional, but some should always be set. In
3753 particular, org-publish needs to know where to look for source files,
3754 and where to put published files.
3756 `:base-directory' Directory containing publishing source files
3757 `:publishing-directory'Directory (possibly remote) where output files
3761 File: org, Node: Selecting files, Next: Publishing action, Prev: Sources and destinations, Up: Configuration
3763 11.1.3 Selecting files
3764 ----------------------
3766 By default, all files with extension `.org' in the base directory are
3767 considered part of the project. This can be modified by setting the
3769 `:base-extension' Extension (without the dot!) of source files. This
3770 actually is a regular expression.
3771 `:exclude' Regular expression to match file names that should
3772 not be published, even though they have been selected
3773 on the basis of their extension.
3774 `:include' List of files to be included regardless of
3775 `:base-extension' and `:exclude'.
3778 File: org, Node: Publishing action, Next: Publishing options, Prev: Selecting files, Up: Configuration
3780 11.1.4 Publishing Action
3781 ------------------------
3783 Publishing means that a file is copied to the destination directory and
3784 possibly transformed in the process. The default transformation is to
3785 export Org-mode files as HTML files, and this is done by the function
3786 `org-publish-org-to-html' which calls the HTML exporter (*note HTML
3787 export::). Other files like images only need to be copied to the
3788 publishing destination. For non-Org-mode files, you need to specify
3789 the publishing function.
3791 `:publishing-function' Function executing the publication of a file.
3793 The function must accept two arguments: a property list containing at
3794 least a `:publishing-directory' property, and the name of the file to
3795 be published. It should take the specified file, make the necessary
3796 transformation (if any) and place the result into the destination
3797 folder. You can write your own publishing function, but `org-publish'
3798 provides one for attachments (files that only need to be copied):
3799 `org-publish-attachment'.
3802 File: org, Node: Publishing options, Next: Publishing links, Prev: Publishing action, Up: Configuration
3804 11.1.5 Options for the HTML exporter
3805 ------------------------------------
3807 The property list can be used to set many export options for the HTML
3808 exporter. In most cases, these properties correspond to user variables
3809 in Org-mode. The table below lists these properties along with the
3810 variable they belong to. See the documentation string for the
3811 respective variable for details.
3813 `:language' `org-export-default-language'
3814 `:headline-levels' `org-export-headline-levels'
3815 `:section-numbers' `org-export-with-section-numbers'
3816 `:table-of-contents' `org-export-with-toc'
3817 `:archived-trees' `org-export-with-archived-trees'
3818 `:emphasize' `org-export-with-emphasize'
3819 `:sub-superscript' `org-export-with-sub-superscripts'
3820 `:TeX-macros' `org-export-with-TeX-macros'
3821 `:LaTeX-fragments' `org-export-with-LaTeX-fragments'
3822 `:fixed-width' `org-export-with-fixed-width'
3823 `:timestamps' `org-export-with-timestamps'
3825 `:tags' `org-export-with-tags'
3827 `:tables' `org-export-with-tables'
3828 `:table-auto-headline' `org-export-highlight-first-table-line'
3829 `:style' `org-export-html-style'
3830 `:convert-org-links' `org-export-html-link-org-files-as-html'
3831 `:inline-images' `org-export-html-inline-images'
3832 `:expand-quoted-html' `org-export-html-expand'
3833 `:timestamp' `org-export-html-with-timestamp'
3834 `:publishing-directory'`org-export-publishing-directory'
3835 `:preamble' `org-export-html-preamble'
3836 `:postamble' `org-export-html-postamble'
3837 `:auto-preamble' `org-export-html-auto-preamble'
3838 `:auto-postamble' `org-export-html-auto-postamble'
3839 `:author' `user-full-name'
3840 `:email' `user-mail-address'
3842 When a property is given a value in org-publish-project-alist, its
3843 setting overrides the value of the corresponding user variable (if any)
3844 during publishing. options set within a file (*note Export options::),
3845 however, override everything.
3848 File: org, Node: Publishing links, Next: Project page index, Prev: Publishing options, Up: Configuration
3850 11.1.6 Links between published files
3851 ------------------------------------
3853 To create a link from one Org-mode file to another, you would use
3854 something like `[[file:foo.org][The foo]]' or simply `file:foo.org.'
3855 (*note Hyperlinks::). Upon publishing this link becomes a link to
3856 `foo.html'. In this way, you can interlink the pages of your "org web"
3857 project and the links will work as expected when you publish them to
3860 You may also link to related files, such as images. Provided you are
3861 careful with relative pathnames, and provided you have also configured
3862 org-publish to upload the related files, these links will work too.
3863 *Note Complex example:: for an example of this usage.
3865 Sometime an Org-mode file to be published may contain links that are
3866 only valid in your production environment, but not in the publishing
3867 location. In this case, use the property
3869 `:link-validation-function' Function to validate links
3871 to define a function for checking link validity. This function must
3872 accept two arguments, the file name and a directory relative to which
3873 the file name is interpreted in the production environment. If this
3874 function returns `nil', then the HTML generator will only insert a
3875 description into the HTML file, but no link. One option for this
3876 function is `org-publish-validate-link' which checks if the given file
3877 is part of any project in `org-publish-project-alist'.
3880 File: org, Node: Project page index, Prev: Publishing links, Up: Configuration
3882 11.1.7 Project page index
3883 -------------------------
3885 The following properties may be used to control publishing of an index
3886 of files or summary page for a given project.
3888 `:auto-index' When non-nil, publish an index during
3889 org-publish-current-project or org-publish-all.
3890 `:index-filename' Filename for output of index. Defaults to `index.org'
3891 (which becomes `index.html').
3892 `:index-title' Title of index page. Defaults to name of file.
3893 `:index-function' Plugin function to use for generation of index.
3894 Defaults to `org-publish-org-index', which generates
3895 a plain list of links to all files in the project.
3898 File: org, Node: Sample configuration, Next: Triggering publication, Prev: Configuration, Up: Publishing
3900 11.2 Sample configuration
3901 =========================
3903 Below we provide two example configurations. The first one is a simple
3904 project publishing only a set of Org-mode files. The second example is
3905 more complex, with a multi-component project.
3909 * Simple example:: One-component publishing
3910 * Complex example:: A multi-component publishing example
3913 File: org, Node: Simple example, Next: Complex example, Prev: Sample configuration, Up: Sample configuration
3915 11.2.1 Example: simple publishing configuration
3916 -----------------------------------------------
3918 This example publishes a set of Org-mode files to the `public_html'
3919 directory on the local machine.
3921 (setq org-publish-project-alist
3923 :base-directory "~/org/"
3924 :publishing-directory "~/public_html"
3925 :section-numbers nil
3926 :table-of-contents nil
3927 :style "<link rel=stylesheet
3928 href=\"../other/mystyle.css\"
3929 type=\"text/css\">")))
3932 File: org, Node: Complex example, Prev: Simple example, Up: Sample configuration
3934 11.2.2 Example: complex publishing configuration
3935 ------------------------------------------------
3937 This more complicated example publishes an entire website, including
3938 org files converted to HTML, image files, emacs lisp source code, and
3939 stylesheets. The publishing-directory is remote and private files are
3942 To ensure that links are preserved, care should be taken to replicate
3943 your directory structure on the web server, and to use relative file
3944 paths. For example, if your org files are kept in `~/org' and your
3945 publishable images in `~/images', you'd link to an image with
3946 file:../images/myimage.png
3947 On the web server, the relative path to the image should be the
3948 same. You can accomplish this by setting up an "images" folder in the
3949 right place on the webserver, and publishing images to it.
3951 (setq org-publish-project-alist
3953 :base-directory "~/org/"
3954 :base-extension "org"
3955 :publishing-directory "/ssh:user@host:~/html/notebook/"
3956 :publishing-function org-publish-org-to-html
3957 :exclude "PrivatePage.org" ;; regexp
3959 :section-numbers nil
3960 :table-of-contents nil
3961 :style "<link rel=stylesheet
3962 href=\"../other/mystyle.css\" type=\"text/css\">"
3964 :auto-postamble nil)
3967 :base-directory "~/images/"
3968 :base-extension "jpg\\|gif\\|png"
3969 :publishing-directory "/ssh:user@host:~/html/images/"
3970 :publishing-function org-publish-attachment)
3973 :base-directory "~/other/"
3974 :base-extension "css\\|el"
3975 :publishing-directory "/ssh:user@host:~/html/other/"
3976 :publishing-function org-publish-attachment)
3977 ("website" :components ("orgfiles" "images" "other"))))
3980 File: org, Node: Triggering publication, Prev: Sample configuration, Up: Publishing
3982 11.3 Triggering publication
3983 ===========================
3985 Once org-publish is properly configured, you can publish with the
3986 following functions:
3989 Prompt for a specific project and publish all files that belong to
3993 Publish the project containing the current file.
3996 Publish only the current file.
3999 Publish all projects.
4001 Org uses timestamps to track when a file has changed. The above
4002 functions normally only publish changed files. You can override this and
4003 force publishing of all files by giving a prefix argument.
4006 File: org, Node: Miscellaneous, Next: Extensions and Hacking, Prev: Publishing, Up: Top
4013 * Completion:: M-TAB knows what you need
4014 * Customization:: Adapting Org-mode to your taste
4015 * In-buffer settings:: Overview of the #+KEYWORDS
4016 * The very busy C-c C-c key:: When in doubt, press C-c C-c
4017 * Clean view:: Getting rid of leading stars in the outline
4018 * TTY keys:: Using Org-mode on a tty
4019 * Interaction:: Other Emacs packages
4020 * Bugs:: Things which do not work perfectly
4023 File: org, Node: Completion, Next: Customization, Prev: Miscellaneous, Up: Miscellaneous
4028 Org-mode supports in-buffer completion. This type of completion does
4029 not make use of the minibuffer. You simply type a few letters into the
4030 buffer and use the key to complete text right there.
4033 Complete word at point
4034 * At the beginning of a headline, complete TODO keywords.
4036 * After `\', complete TeX symbols supported by the exporter.
4038 * After `*', complete CamelCase versions of all headlines in the
4041 * After `:', complete tags used elsewhere in the buffer.
4043 * After `#+', complete the special keywords like `TYP_TODO' or
4044 `OPTIONS' which set file-specific options for Org-mode. When
4045 the option keyword is already complete, pressing `M-<TAB>'
4046 again will insert example settings for this keyword.
4048 * Elsewhere, complete dictionary words using ispell.
4051 File: org, Node: Customization, Next: In-buffer settings, Prev: Completion, Up: Miscellaneous
4056 There are more than 100 variables that can be used to customize
4057 Org-mode. For the sake of compactness of the manual, we are not
4058 describing the variables here. A structured overview of customization
4059 variables is available with `M-x org-customize'. Or select `Browse Org
4060 Group' from the `Org->Customization' menu. Many settings can also be
4061 activated on a per-file basis, by putting special lines into the buffer
4062 (*note In-buffer settings::).
4065 File: org, Node: In-buffer settings, Next: The very busy C-c C-c key, Prev: Customization, Up: Miscellaneous
4067 12.3 Summary of in-buffer settings
4068 ==================================
4070 Org-mode uses special lines in the buffer to define settings on a
4071 per-file basis. These lines start with a `#+' followed by a keyword, a
4072 colon, and then individual words defining a setting. Several setting
4073 words can be in the same line, but you can also have multiple lines for
4074 the keyword. While these settings are described throughout the manual,
4075 here is a summary. After changing any of those lines in the buffer,
4076 press `C-c C-c' with the cursor still in the line to activate the
4077 changes immediately. Otherwise they become effective only when the
4078 file is visited again in a new Emacs session.
4081 This line sets options to be used at startup of org-mode, when an
4082 Org-mode file is being visited. The first set of options deals
4083 with the initial visibility of the outline tree. The
4084 corresponding variable for global default settings is
4085 `org-startup-folded', with a default value `t', which means
4087 overview top-level headlines only
4088 content all headlines
4089 showall no folding at all, show everything
4090 Then there are options for aligning tables upon visiting a file.
4091 This is useful in files containing narrowed table columns. The
4092 corresponding variable is `org-startup-align-all-tables', with a
4093 default value `nil'.
4094 align align all tables
4095 noalign don't align tables on startup
4096 Logging when a TODO item is marked DONE (variable `org-log-done')
4097 can be configured using these options.
4098 logging record a timestamp when an item is marked DONE
4099 nologging don't record when items are marked DONE
4100 Here are the options for hiding leading stars in outline headings.
4101 The corresponding variables are `org-hide-leading-stars' and
4102 `org-odd-levels-only', both with a default setting `nil' (meaning
4103 `showstars' and `oddeven').
4104 hidestars make all but one of the stars starting a headline invisible.
4105 showstars show all stars starting a headline
4106 odd allow only odd outline levels (1,3,...)
4107 oddeven allow all outline levels
4109 `#+SEQ_TODO: #+TYP_TODO:'
4110 These lines set the TODO keywords and their interpretation in the
4111 current file. The corresponding variables are `org-todo-keywords'
4112 and `org-todo-interpretation'.
4114 `#+TAGS: TAG1(c1) TAG2(c2)'
4115 These lines (several such lines are allowed) specify the legal
4116 tags in this file, and (potentially) the corresponding _fast tag
4117 selection_ keys. The corresponding variable is `org-tag-alist'.
4120 This line sets the category for the agenda file. The category
4121 applies for all subsequent lines until the next `#+CATEGORY' line,
4122 or the end of the file.
4125 This line contains the formulas for the table directly above the
4128 `#+TITLE:, #+AUTHOR:, #+EMAIL:, #+LANGUAGE:, #+TEXT:, #+OPTIONS:'
4129 These lines provide settings for exporting files. For more
4130 details see *Note Export options::.
4133 File: org, Node: The very busy C-c C-c key, Next: Clean view, Prev: In-buffer settings, Up: Miscellaneous
4135 12.4 The very busy C-c C-c key
4136 ==============================
4138 The key `C-c C-c' has many purposes in org-mode, which are all
4139 mentioned scattered throughout this manual. One specific function of
4140 this key is to add _tags_ to a headline (*note Tags::). In many other
4141 circumstances it means something like _Hey Org-mode, look here and
4142 update according to what you see here_. Here is a summary of what this
4143 means in different contexts.
4145 - If there are highlights in the buffer from the creation of a sparse
4146 tree, or from clock display, remove these highlights.
4148 - If the cursor is in one of the special `#+KEYWORD' lines, this
4149 triggers scanning the buffer for these lines and updating the
4152 - If the cursor is inside a table, realign the table. This command
4153 works even if the automatic table editor has been turned off.
4155 - If the cursor is on a `#+TBLFM' line, re-apply the formulas to the
4158 - If the cursor is inside a table created by the `table.el' package,
4159 activate that table.
4161 - If the current buffer is a remember buffer, close the note and
4162 file it. With a prefix argument, file it, without further
4163 interaction, to the default location.
4165 - If the cursor is on a `<<<target>>>', update radio targets and
4166 corresponding links in this buffer.
4168 - If the cursor is in a plain list item with a checkbox, toggle the
4169 status of the checkbox.
4171 - If the cursor is on a numbered item in a plain list, renumber the
4175 File: org, Node: Clean view, Next: TTY keys, Prev: The very busy C-c C-c key, Up: Miscellaneous
4177 12.5 A cleaner outline view
4178 ===========================
4180 Some people find it noisy and distracting that the Org-mode headlines
4181 are starting with a potentially large number of stars. For example the
4182 tree from *Note Headlines:::
4184 * Top level headline
4190 * Another top level headline
4192 Unfortunately this is deeply ingrained into the code of Org-mode and
4193 cannot be easily changed. You can, however, modify the display in such
4194 a way that all leading stars become invisible and the outline more easy
4195 to read. To do this, customize the variable `org-hide-leading-stars'
4198 (setq org-hide-leading-stars t)
4200 or change this on a per-file basis with one of the lines (anywhere in
4203 #+STARTUP: showstars
4204 #+STARTUP: hidestars
4206 Press `C-c C-c' with the cursor in a `STARTUP' line to activate the
4209 With stars hidden, the tree becomes:
4211 * Top level headline
4217 * Another top level headline
4219 Note that the leading stars are not truly replaced by whitespace, they
4220 are only fontified with the face `org-hide' that uses the background
4221 color as font color. If are are not using either white or black
4222 background, you may have to customize this face to get the wanted
4223 effect. Another possibility is to set this font such that the extra
4224 stars are almost invisible, for example using the color `grey90' on a
4227 Things become cleaner still if you skip all the even levels and use
4228 only odd levels 1, 3, 5..., effectively adding two stars to go from one
4229 outline level to the next:
4231 * Top level headline
4237 * Another top level headline
4239 In order to make the structure editing and export commands handle this
4240 convention correctly, use
4242 (setq org-odd-levels-only t)
4244 or set this on a per-file basis with one of the following lines (don't
4245 forget to press `C-c C-c' with the cursor in the startup line to
4246 activate changes immediately).
4251 You can convert an Org-mode file from single-star-per-level to the
4252 double-star-per-level convention with `M-x org-convert-to-odd-levels
4253 RET' in that file. The reverse operation is `M-x
4254 org-convert-to-oddeven-levels'.
4257 File: org, Node: TTY keys, Next: Interaction, Prev: Clean view, Up: Miscellaneous
4259 12.6 Using org-mode on a tty
4260 ============================
4262 Org-mode uses a number of keys that are not accessible on a tty. This
4263 applies to most special keys like cursor keys, <TAB> and <RET>, when
4264 these are combined with modifier keys like <Meta> and/or <Shift>.
4265 Org-mode uses these bindings because it needs to provide keys for a
4266 large number of commands, and because these keys appeared particularly
4267 easy to remember. In order to still be able to access the core
4268 functionality of Org-mode on a tty, alternative bindings are provided.
4269 Here is a complete list of these bindings, which are obviously more
4270 cumbersome to use. Note that sometimes a work-around can be better.
4271 For example changing a time stamp is really only fun with `S-<cursor>'
4272 keys. On a tty you would rather use `C-c .' to re-insert the
4275 Default Alternative 1 Alternative 2
4276 `S-<TAB>' `C-u <TAB>'
4277 `M-<left>' `C-c C-x l' `<Esc> <left>'
4278 `M-S-<left>'`C-c C-x L'
4279 `M-<right>' `C-c C-x r' `<Esc>
4281 `M-S-<right>'`C-c C-x R'
4282 `M-<up>' `C-c C-x u' `<Esc> <up>'
4283 `M-S-<up>' `C-c C-x U'
4284 `M-<down>' `C-c C-x d' `<Esc> <down>'
4285 `M-S-<down>'`C-c C-x D'
4286 `S-<RET>' `C-c C-x c'
4287 `M-<RET>' `C-c C-x m' `<Esc> <RET>'
4288 `M-S-<RET>' `C-c C-x M'
4291 `S-<right>' `C-c C-x
4299 File: org, Node: Interaction, Next: Bugs, Prev: TTY keys, Up: Miscellaneous
4301 12.7 Interaction with other packages
4302 ====================================
4304 Org-mode lives in the world of GNU Emacs and interacts in various ways
4305 with other code out there.
4309 * Cooperation:: Packages Org-mode cooperates with
4310 * Conflicts:: Packages that lead to conflicts
4313 File: org, Node: Cooperation, Next: Conflicts, Prev: Interaction, Up: Interaction
4315 12.7.1 Packages that Org-mode cooperates with
4316 ---------------------------------------------
4318 `calc.el' by Dave Gillespie
4319 Org-mode uses the calc package for implementing spreadsheet
4320 functionality in its tables (*note Table calculations::).
4321 Org-modes checks for the availability of calc by looking for the
4322 function `calc-eval' which should be autoloaded in your setup if
4323 calc has been installed properly. As of Emacs 22, calc is part of
4324 the Emacs distribution. Another possibility for interaction
4325 between the two packages is using calc for embedded calculations.
4326 *Note Embedded Mode: (calc)Embedded Mode.
4328 `constants.el' by Carsten Dominik
4329 In a table formula (*note Table calculations::), it is possible to
4330 use names for natural constants or units. Instead of defining
4331 your own constants in the variable `org-table-formula-constants',
4332 install the `constants' package which defines a large number of
4333 constants and units, and lets you use unit prefixes like `M' for
4334 `Mega' etc. You will need version 2.0 of this package, available
4335 at `http://www.astro.uva.nl/~dominik/Tools'. Org-mode checks for
4336 the function `constants-get', which has to be autoloaded in your
4337 setup. See the installation instructions in the file
4340 `cdlatex.el' by Carsten Dominik
4341 Org-mode can make use of the cdlatex package to efficiently enter
4342 LaTeX fragments into Org-mode files. See *Note CDLaTeX mode::.
4344 `remember.el' by John Wiegley
4345 Org mode cooperates with remember, see *Note Remember::.
4346 `Remember.el' is not part of Emacs, find it on the web.
4348 `table.el' by Takaaki Ota
4349 Org mode cooperates with table.el, see *Note table.el::.
4350 `table.el' is part of Emacs 22.
4353 File: org, Node: Conflicts, Prev: Cooperation, Up: Interaction
4355 12.7.2 Packages that lead to conflicts with Org-mode
4356 ----------------------------------------------------
4358 `allout.el' by Ken Manheimer
4359 Startup of Org-mode may fail with the error message
4360 `(wrong-type-argument keymapp nil)' when there is an outdated
4361 version `allout.el' on the load path, for example the version
4362 distributed with Emacs 21.x. Upgrade to Emacs 22 and this problem
4363 will disappear. If for some reason you cannot do this, make sure
4364 that org.el is loaded _before_ `allout.el', for example by putting
4365 `(require 'org)' early enough into your `.emacs' file.
4367 `CUA.el' by Kim. F. Storm
4368 Keybindings in Org-mode conflict with the `S-<cursor>' keys used
4369 by CUA-mode (as well as pc-select-mode and s-region-mode) to
4370 select and extend the region. If you want to use one of these
4371 packages along with Org-mode, configure the variable
4372 `org-CUA-compatible'. When set, Org-mode will move the following
4373 keybindings in org-mode files, and in the agenda buffer (but not
4374 during date selection).
4376 S-UP -> M-p S-DOWN -> M-n
4377 S-LEFT -> M-- S-RIGHT -> M-+
4380 Yes, these are unfortunately more difficult to remember. If you
4381 want to have other replacement keys, look at the variable
4382 `org-disputed-keys'.
4384 `windmove.el' by Hovav Shacham
4385 Also this package uses the `S-<cursor>' keys, so everything written
4386 in the paragraph above about CUA mode also applies here.
4389 File: org, Node: Bugs, Prev: Interaction, Up: Miscellaneous
4394 Here is a list of things that should work differently, but which I have
4395 found too hard to fix.
4397 * If a table field starts with a link, and if the corresponding table
4398 column is narrowed (*note Narrow columns::) to a width too small to
4399 display the link, the field would look entirely empty even though
4400 it is not. To prevent this, Org-mode throws an error. The
4401 work-around is to make the column wide enough to fit the link, or
4402 to add some text (at least 2 characters) before the link in the
4405 * Narrowing table columns does not work on XEmacs, because the
4406 `format' function does not transport text properties.
4408 * Text in an entry protected with the `QUOTE' keyword should not
4411 * When the application called by `C-c C-o' to open a file link fails
4412 (for example because the application does not exist or refuses to
4413 open the file), it does so silently. No error message is
4416 * The remote-editing commands in the agenda buffer cannot be undone
4417 with `undo' called from within the agenda buffer. But you can go
4418 to the corresponding buffer (using <TAB> or <RET> and execute
4421 * Recalculating a table line applies the formulas from left to right.
4422 If a formula uses _calculated_ fields further down the row,
4423 multiple recalculation may be needed to get all fields consistent.
4425 * A single letter cannot be made bold, for example `*a*'.
4427 * The exporters work well, but could be made more efficient.
4430 File: org, Node: Extensions and Hacking, Next: History and Acknowledgments, Prev: Miscellaneous, Up: Top
4432 Appendix A Extensions, Hooks and Hacking
4433 ****************************************
4435 This appendix lists extensions for Org-mode written by other authors.
4436 It also covers some aspects where users can easily extend the
4437 functionality of Org-mode.
4441 * Extensions:: Existing 3rd-part extensions
4442 * Dynamic blocks:: Automatically filled blocks
4445 File: org, Node: Extensions, Next: Dynamic blocks, Prev: Extensions and Hacking, Up: Extensions and Hacking
4447 A.1 Third-party extensions for Org-mode
4448 =======================================
4450 The following extensions for Org-mode have been written by other people:
4452 `org-mouse.el' by Piotr Zielinski
4453 This package implements extended mouse functionality for Org-mode.
4454 It allows you to cycle visibility and to edit the document
4455 structure with the mouse. Best of all, it provides a
4456 context-sensitive menu on <mouse-3> that changes depending on the
4457 context of a mouse-click. `org-mouse.el' is freely available at
4458 `http://www.cl.cam.ac.uk/~pz215/files/org-mouse.el'.
4460 `org-publish.el' by David O'Toole
4461 This package provides facilities for publishing related sets of
4462 Org-mode files together with linked files like images as a
4463 webpages. It is highly configurable and can be used for other
4464 publishing purposes as well. As of Org-mode version 4.30,
4465 `org-publish.el' is part of the Org-mode distribution. It is not
4466 yet part of Emacs, however, a delay caused by the preparations for
4467 the 22.1 release. In the mean time, `org-publish.el' can be
4468 downloaded from David's site:
4469 `http://dto.freeshell.org/e/org-publish.el'.
4471 `org-blog.el' by David O'Toole
4472 A blogging plug-in for `org-publish.el'.
4473 `http://dto.freeshell.org/notebook/OrgMode.html'.
4475 `org-blogging.el' by Bastien Guerry
4476 Publish Org-mode files as blogs.
4477 `http://www.cognition.ens.fr/~guerry/org-blogging.html'.
4480 File: org, Node: Dynamic blocks, Prev: Extensions, Up: Extensions and Hacking
4485 Org-mode documents can contain _dynamic blocks_. These are specially
4486 marked regions that are updated by some user-written function. A good
4487 example for such a block is the clock table inserted by the command
4488 `C-c C-x C-r' (*note Clocking work time::).
4490 Dynamic block are enclosed by a BEGIN-END structure that assigns a
4491 name to the block and can also specify parameters for the function
4492 producing the content of the block.
4494 #+BEGIN: myblock :parameter1 value1 :parameter2 value2 ...
4498 Dynamic blocks are updated with the following commands
4501 Update dynamic block at point.
4504 Update all dynamic blocks in the current file.
4506 Updating a dynamic block means to remove all the text between BEGIN
4507 and END, parse the BEGIN line for parameters and then call the specific
4508 writer function for this block to insert the new content. For a block
4509 with name `myblock', the writer function is `org-dblock-write:myblock'
4510 with as only parameter a property list with the parameters given in the
4511 begin line. Here is a trivial example of a block that keeps track of
4512 when the block update function was last run:
4514 #+BEGIN: block-update-time :format "on %m/%d/%Y at %H:%M"
4518 The corresponding block writer function could look like this:
4520 (defun org-dblock-write:block-update-time (params)
4521 (let ((fmt (or (plist-get params :format) "%d. %m. %Y")))
4522 (insert "Last block update at: "
4523 (format-time-string fmt (current-time)))))
4525 If you want to make sure that all dynamic blocks are always
4526 up-to-date, you could add the function `org-update-all-dblocks' to a
4527 hook, for example `before-save-hook'. `org-update-all-dblocks' is
4528 written in a way that is does nothing in buffers that are not in
4532 File: org, Node: History and Acknowledgments, Next: Index, Prev: Extensions and Hacking, Up: Top
4534 Appendix B History and Acknowledgments
4535 **************************************
4537 Org-mode was borne in 2003, out of frustration over the user interface
4538 of the Emacs outline-mode. All I wanted was to make working with an
4539 outline tree possible without having to remember more than 10 commands
4540 just for hiding and unhiding parts of the outline tree, and to allow to
4541 restructure a tree easily. Visibility cycling and structure editing
4542 were originally implemented in the package `outline-magic.el', but
4543 quickly moved to the more general `org.el'. TODO entries, basic time
4544 stamps, and table support were added next, and highlight the two main
4545 goals that Org-mode still has today: To create a new, outline-based,
4546 plain text mode with innovative and intuitive editing features, and to
4547 incorporate project planning functionality directly into a notes file.
4549 Since the first release, hundreds of emails to me or on
4550 `emacs-orgmode@gnu.org' have provided a constant stream of bug reports,
4551 feedback, new ideas, and sometimes even patches and add-on code. Many
4552 thanks to everyone who has helped to improve this package. I am trying
4553 to keep here a list of the people who had significant influence in
4554 shaping one or more aspects of Org-mode. The list may not be complete,
4555 if I have forgotten someone, please accept my apologies and let me know.
4557 * Thomas Baumann contributed the code for links to the MH-E email
4560 * Alex Bochannek provided a patch for rounding time stamps.
4562 * Charles Cave's suggestion sparked the implementation of templates
4565 * Pavel Chalmoviansky influenced the agenda treatment of items with
4568 * Gregory Chernov patched support for lisp forms into table
4569 calculations and improved XEmacs compatibility, in particular by
4570 porting `nouline.el' to XEmacs.
4572 * Sacha Chua suggested to copy some linking code from Planner.
4574 * Eddward DeVilla proposed Checkbox statistics.
4576 * Kees Dullemond inspired the use of narrowed tabled columns.
4578 * Christian Egli converted the documentation into TeXInfo format,
4579 patched CSS formatting into the HTML exporter, and inspired the
4582 * Nic Ferrier contributed mailcap and XOXO support.
4584 * Niels Giessen had the idea to automatically archive DONE trees.
4586 * Bastien Guerry provided extensive feedback.
4588 * Kai Grossjohann pointed out key-binding conflicts with other
4591 * Leon Liu asked for embedded LaTeX and tested it.
4593 * Stefan Monnier provided a patch to keep the Emacs-Lisp compiler
4596 * Todd Neal provided patches for links to Info files and elisp forms.
4598 * Tim O'Callaghan suggested in-file links, search options for general
4599 file links, and TAGS.
4601 * Oliver Oppitz suggested multi-state TODO items.
4603 * Scott Otterson sparked the introduction of descriptive text for
4604 links, among other things.
4606 * Pete Phillips helped the development of the TAGS feature.
4608 * T.V. Raman reported bugs and suggested improvements.
4610 * Matthias Rempe (Oelde) provided ideas, Windows support, and quality
4613 * Kevin Rogers contributed code to access VM files on remote hosts.
4615 * Frank Ruell solved the mystery of the `keymapp nil' bug, a
4616 conflict with `allout.el'.
4618 * Philip Rooke created the Org-mode reference card and provided lots
4621 * Christian Schlauer proposed angular brackets around links, among
4624 * Linking to VM/BBDB/GNUS was inspired by Tom Shannon's
4625 `organizer-mode.el'.
4627 * Daniel Sinder came up with the idea of internal archiving by
4630 * David O'Toole wrote `org-publish.el' and drafted the manual
4631 chapter about publishing.
4633 * Ju"rgen Vollmer contributed code generating the table of contents
4636 * Chris Wallace provided a patch implementing the `QUOTE' keyword.
4638 * David Wainberg suggested archiving, and improvements to the linking
4641 * John Wiegley wrote `emacs-wiki.el' and `planner.el'. The
4642 development of Org-mode was fully independent, and both systems are
4643 really different beasts in their basic ideas and implementation
4644 details. I later looked at John's code, however, and learned from
4645 his implementation of (i) links where the link itself is hidden
4646 and only a description is shown, and (ii) popping up a calendar to
4649 * Carsten Wimmer suggested some changes and helped fix a bug in
4652 * Roland Winkler requested additional keybindings to make Org-mode
4655 * Piotr Zielinski wrote `org-mouse.el' and showed how to follow
4659 File: org, Node: Index, Next: Key Index, Prev: History and Acknowledgments, Up: Top
4667 * acknowledgments: History and Acknowledgments.
4669 * action, for publishing: Publishing action. (line 6)
4670 * activation: Activation. (line 6)
4671 * active region <1>: HTML export. (line 10)
4672 * active region <2>: ASCII export. (line 9)
4673 * active region <3>: Built-in table editor.
4675 * active region: Structure editing. (line 51)
4676 * agenda: Weekly/Daily agenda. (line 6)
4677 * agenda commands, custom: Agenda dispatcher. (line 6)
4678 * agenda dispatcher: Agenda dispatcher. (line 6)
4679 * agenda files, removing buffers: Agenda commands. (line 211)
4680 * agenda views: Agenda views. (line 6)
4681 * agenda, for single file: Timeline. (line 6)
4682 * allout.el: Conflicts. (line 6)
4683 * angular brackets, around links: External links. (line 38)
4684 * applescript, for calendar update: iCalendar export. (line 38)
4685 * archive locations: Moving subtrees. (line 21)
4686 * archiving: Archiving. (line 6)
4687 * ASCII export: ASCII export. (line 6)
4688 * author: Feedback. (line 6)
4689 * autoload: Activation. (line 6)
4690 * BBDB links: External links. (line 6)
4691 * bold text: Enhancing text. (line 15)
4692 * bug reports: Feedback. (line 6)
4693 * bugs: Bugs. (line 6)
4694 * calc package: Table calculations. (line 6)
4695 * calc.el: Cooperation. (line 6)
4696 * calculations, in tables <1>: Table calculations. (line 6)
4697 * calculations, in tables: Built-in table editor.
4699 * calendar integration: Calendar/Diary integration.
4701 * calendar, for selecting date: Creating timestamps. (line 71)
4702 * CamelCase link completion: Completion. (line 6)
4703 * CamelCase links: Internal links. (line 6)
4704 * CamelCase links, completion of: CamelCase links. (line 6)
4705 * category: Categories. (line 6)
4706 * cdlatex.el: Cooperation. (line 29)
4707 * checkbox statistics: Checkboxes. (line 24)
4708 * checkboxes: Checkboxes. (line 6)
4709 * children, subtree visibility state: Visibility cycling. (line 10)
4710 * clean outline view: Clean view. (line 6)
4711 * CLOCK keyword: Time stamps. (line 61)
4712 * CLOSED keyword: Time stamps. (line 55)
4713 * column formula: Column formulas. (line 6)
4714 * commands, in agenda buffer: Agenda commands. (line 6)
4715 * comment lines: Comment lines. (line 6)
4716 * completion, of CamelCase links <1>: Completion. (line 6)
4717 * completion, of CamelCase links: CamelCase links. (line 6)
4718 * completion, of dictionary words: Completion. (line 6)
4719 * completion, of file names: Handling links. (line 43)
4720 * completion, of links: Handling links. (line 27)
4721 * completion, of option keywords <1>: Completion. (line 6)
4722 * completion, of option keywords: Export options. (line 6)
4723 * Completion, of option keywords: Per file keywords. (line 17)
4724 * completion, of tags <1>: Completion. (line 6)
4725 * completion, of tags: Setting tags. (line 11)
4726 * completion, of TeX symbols: Completion. (line 6)
4727 * completion, of TODO keywords <1>: Completion. (line 6)
4728 * completion, of TODO keywords: Workflow states. (line 12)
4729 * constants, in calculations: Formula syntax. (line 26)
4730 * constants.el: Cooperation. (line 14)
4731 * contents, global visibility state: Visibility cycling. (line 22)
4732 * copying, of subtrees: Structure editing. (line 6)
4733 * creating timestamps: Creating timestamps. (line 6)
4734 * CUA.el: Conflicts. (line 15)
4735 * custom agenda commands: Agenda dispatcher. (line 6)
4736 * custom search strings: Custom searches. (line 6)
4737 * customization: Customization. (line 6)
4738 * cutting, of subtrees: Structure editing. (line 6)
4739 * cycling, of TODO states: TODO basics. (line 13)
4740 * cycling, visibility: Visibility cycling. (line 6)
4741 * date stamps: Time stamps. (line 6)
4742 * date, reading in minibuffer: Creating timestamps. (line 71)
4743 * DEADLINE keyword: Time stamps. (line 43)
4744 * deadlines: Time stamps. (line 6)
4745 * demotion, of subtrees: Structure editing. (line 6)
4746 * diary entries, creating from agenda: Agenda commands. (line 179)
4747 * diary integration: Calendar/Diary integration.
4749 * dictionary word completion: Completion. (line 6)
4750 * directories, for publishing: Sources and destinations.
4752 * dispatching agenda commands: Agenda dispatcher. (line 6)
4753 * document structure: Document structure. (line 6)
4754 * DONE, final TODO keyword: Per file keywords. (line 20)
4755 * editing tables: Tables. (line 6)
4756 * editing, of table formulas: Editing/debugging formulas.
4758 * elisp links: External links. (line 6)
4759 * emphasized text: Export options. (line 25)
4760 * enhancing text: Enhancing text. (line 6)
4761 * evaluate time range: Creating timestamps. (line 66)
4762 * exporting: Exporting. (line 6)
4763 * exporting, not: Comment lines. (line 6)
4764 * extended TODO keywords: TODO extensions. (line 6)
4765 * external archiving: Moving subtrees. (line 6)
4766 * external links: External links. (line 6)
4767 * external links, in HTML export: HTML export. (line 35)
4768 * FAQ: Summary. (line 41)
4769 * feedback: Feedback. (line 6)
4770 * file links: External links. (line 6)
4771 * file links, searching: Search options. (line 6)
4772 * file name completion: Handling links. (line 43)
4773 * files, adding to agenda list: Agenda files. (line 12)
4774 * files, selecting for publishing: Selecting files. (line 6)
4775 * fixed width: Enhancing text. (line 25)
4776 * fixed-width sections: Export options. (line 25)
4777 * folded, subtree visibility state: Visibility cycling. (line 10)
4778 * folding, sparse trees: Sparse trees. (line 6)
4779 * following links: Handling links. (line 58)
4780 * format specifier: Formula syntax. (line 34)
4781 * format, of links: Link format. (line 6)
4782 * formula editing: Editing/debugging formulas.
4784 * formula syntax: Formula syntax. (line 6)
4785 * formula, for named table field: Named-field formulas.
4787 * formula, for table column: Column formulas. (line 6)
4788 * formula, in tables: Built-in table editor.
4790 * global cycling: Visibility cycling. (line 22)
4791 * global keybindings: Activation. (line 6)
4792 * global TODO list: Global TODO list. (line 6)
4793 * global visibility states: Visibility cycling. (line 22)
4794 * GNUS links: External links. (line 6)
4795 * hand-formatted lists: Enhancing text. (line 11)
4796 * headline levels: Export options. (line 25)
4797 * headline levels, for exporting <1>: HTML export. (line 21)
4798 * headline levels, for exporting: ASCII export. (line 18)
4799 * headline navigation: Motion. (line 6)
4800 * headline tagging: Tags. (line 6)
4801 * headline, promotion and demotion: Structure editing. (line 6)
4802 * headlines: Headlines. (line 6)
4803 * hide text: Visibility cycling. (line 6)
4804 * hiding leading stars: Clean view. (line 6)
4805 * history: History and Acknowledgments.
4807 * HTML export: HTML export. (line 6)
4808 * hyperlinks: Hyperlinks. (line 6)
4809 * iCalendar export: iCalendar export. (line 6)
4810 * in-buffer settings: In-buffer settings. (line 6)
4811 * index, of published pages: Project page index. (line 6)
4812 * Info links: External links. (line 6)
4813 * inheritance, of tags: Tag inheritance. (line 6)
4814 * inserting links: Handling links. (line 27)
4815 * installation: Installation. (line 6)
4816 * internal archiving: ARCHIVE tag. (line 6)
4817 * internal links: Internal links. (line 6)
4818 * internal links, in HTML export: HTML export. (line 35)
4819 * introduction: Introduction. (line 6)
4820 * italic text: Enhancing text. (line 15)
4821 * jumping, to headlines: Motion. (line 6)
4822 * keybindings, global: Activation. (line 6)
4823 * keyword options: Per file keywords. (line 6)
4824 * LaTeX fragments: Export options. (line 25)
4825 * LaTeX fragments, export: Enhancing text. (line 18)
4826 * LaTeX interpretation: Embedded LaTeX. (line 6)
4827 * linebreak preservation: Export options. (line 25)
4828 * linebreak, forced: Enhancing text. (line 32)
4829 * link completion: Handling links. (line 27)
4830 * link format: Link format. (line 6)
4831 * links, external: External links. (line 6)
4832 * links, in HTML export: HTML export. (line 35)
4833 * links, internal: Internal links. (line 6)
4834 * links, publishing: Publishing links. (line 6)
4835 * links, returning to: Handling links. (line 84)
4836 * Lisp forms, as table formulas: Lisp formulas. (line 6)
4837 * lists, hand-formatted: Enhancing text. (line 11)
4838 * lists, ordered: Plain lists. (line 6)
4839 * lists, plain: Plain lists. (line 6)
4840 * logging, of progress: Progress logging. (line 6)
4841 * maintainer: Feedback. (line 6)
4842 * mark ring: Handling links. (line 80)
4843 * marking characters, tables: Advanced features. (line 34)
4844 * matching, of tags: Matching headline tags.
4846 * matching, tags: Tags. (line 6)
4847 * MH-E links: External links. (line 6)
4848 * minor mode for tables: orgtbl-mode. (line 6)
4849 * mode, for calc: Formula syntax. (line 34)
4850 * motion, between headlines: Motion. (line 6)
4851 * name, of column or field: Formula syntax. (line 26)
4852 * named field formula: Named-field formulas.
4854 * names as TODO keywords: TODO types. (line 6)
4855 * narrow columns in tables: Narrow columns. (line 6)
4856 * occur, command: Sparse trees. (line 6)
4857 * option keyword completion: Completion. (line 6)
4858 * options, for customization: Customization. (line 6)
4859 * options, for export: Export options. (line 6)
4860 * options, for publishing: Publishing options. (line 6)
4861 * ordered lists: Plain lists. (line 6)
4862 * org-agenda, command: Weekly/Daily agenda. (line 9)
4863 * org-blog.el: Extensions. (line 25)
4864 * org-blogging.el: Extensions. (line 29)
4865 * org-mode, turning on: Activation. (line 22)
4866 * org-mouse.el: Extensions. (line 8)
4867 * org-publish-project-alist: Project alist. (line 6)
4868 * org-publish.el: Extensions. (line 14)
4869 * orgtbl-mode: orgtbl-mode. (line 6)
4870 * outline tree: Headlines. (line 6)
4871 * outline-mode: Outlines. (line 6)
4872 * outlines: Outlines. (line 6)
4873 * overview, global visibility state: Visibility cycling. (line 22)
4874 * packages, interaction with other: Interaction. (line 6)
4875 * pasting, of subtrees: Structure editing. (line 6)
4876 * per file keywords: Per file keywords. (line 6)
4877 * plain lists: Plain lists. (line 6)
4878 * plain text external links: External links. (line 38)
4879 * printing sparse trees: Sparse trees. (line 39)
4880 * priorities: Priorities. (line 6)
4881 * priorities, of agenda items: Sorting of agenda items.
4883 * progress logging: Progress logging. (line 6)
4884 * projects, for publishing: Project alist. (line 6)
4885 * promotion, of subtrees: Structure editing. (line 6)
4886 * publishing: Publishing. (line 6)
4887 * quoted HTML tags: Export options. (line 25)
4888 * ranges, time: Time stamps. (line 6)
4889 * recomputing table fields: Column formulas. (line 27)
4890 * region, active <1>: HTML export. (line 10)
4891 * region, active <2>: ASCII export. (line 9)
4892 * region, active <3>: Built-in table editor.
4894 * region, active: Structure editing. (line 51)
4895 * remember.el <1>: Cooperation. (line 33)
4896 * remember.el: Remember. (line 6)
4897 * richer text: Enhancing text. (line 6)
4898 * RMAIL links: External links. (line 6)
4899 * SCHEDULED keyword: Time stamps. (line 30)
4900 * scheduling: Time stamps. (line 6)
4901 * search option in file links: Search options. (line 6)
4902 * section-numbers: Export options. (line 25)
4903 * setting tags: Setting tags. (line 6)
4904 * SHELL links: External links. (line 6)
4905 * show all, command: Visibility cycling. (line 31)
4906 * show all, global visibility state: Visibility cycling. (line 22)
4907 * show hidden text: Visibility cycling. (line 6)
4908 * single file summary: Timeline. (line 6)
4909 * sorting, of agenda items: Sorting of agenda items.
4911 * sparse tree, for deadlines: Creating timestamps. (line 41)
4912 * sparse tree, for TODO: TODO basics. (line 26)
4913 * sparse tree, tag based: Tags. (line 6)
4914 * sparse trees: Sparse trees. (line 6)
4915 * special keywords: In-buffer settings. (line 6)
4916 * spreadsheet capabilities: Table calculations. (line 6)
4917 * statistics, for checkboxes: Checkboxes. (line 24)
4918 * storing links: Handling links. (line 9)
4919 * structure editing: Structure editing. (line 6)
4920 * structure of document: Document structure. (line 6)
4921 * subtree cycling: Visibility cycling. (line 10)
4922 * subtree visibility states: Visibility cycling. (line 10)
4923 * subtree, cut and paste: Structure editing. (line 6)
4924 * subtree, subtree visibility state: Visibility cycling. (line 10)
4925 * subtrees, cut and paste: Structure editing. (line 6)
4926 * summary: Summary. (line 6)
4927 * syntax, of formulas: Formula syntax. (line 6)
4928 * table editor, builtin: Built-in table editor.
4930 * table editor, table.el: table.el. (line 6)
4931 * table of contents: Export options. (line 25)
4932 * table.el <1>: Cooperation. (line 34)
4933 * table.el: table.el. (line 6)
4934 * tables <1>: Export options. (line 25)
4935 * tables: Tables. (line 6)
4936 * tables, export: Enhancing text. (line 21)
4937 * tag completion: Completion. (line 6)
4938 * tag searches: Tag searches. (line 6)
4939 * tags: Tags. (line 6)
4940 * tags view: Matching headline tags.
4942 * tasks, breaking down: Breaking down tasks. (line 6)
4943 * templates, for remember: Remember. (line 23)
4944 * TeX interpretation: Embedded LaTeX. (line 6)
4945 * TeX macros: Export options. (line 25)
4946 * TeX macros, export: Enhancing text. (line 18)
4947 * TeX symbol completion: Completion. (line 6)
4948 * TeX-like syntax for sub- and superscripts: Export options. (line 25)
4949 * thanks: History and Acknowledgments.
4951 * time stamps: Time stamps. (line 6)
4952 * time, reading in minibuffer: Creating timestamps. (line 71)
4953 * time-sorted view: Timeline. (line 6)
4954 * timeline, single file: Timeline. (line 6)
4955 * timerange: Time stamps. (line 21)
4956 * timestamp: Time stamps. (line 13)
4957 * timestamps, creating: Creating timestamps. (line 6)
4958 * TODO items: TODO items. (line 6)
4959 * TODO keywords completion: Completion. (line 6)
4960 * TODO list, global: Global TODO list. (line 6)
4961 * TODO types: TODO types. (line 6)
4962 * TODO workflow: Workflow states. (line 6)
4963 * transient-mark-mode <1>: HTML export. (line 10)
4964 * transient-mark-mode <2>: ASCII export. (line 9)
4965 * transient-mark-mode <3>: Built-in table editor.
4967 * transient-mark-mode: Structure editing. (line 51)
4968 * trees, sparse: Sparse trees. (line 6)
4969 * trees, visibility: Visibility cycling. (line 6)
4970 * tty keybindings: TTY keys. (line 6)
4971 * types as TODO keywords: TODO types. (line 6)
4972 * underlined text: Enhancing text. (line 15)
4973 * URL links: External links. (line 6)
4974 * USENET links: External links. (line 6)
4975 * variables, for customization: Customization. (line 6)
4976 * vectors, in table calculations: Formula syntax. (line 23)
4977 * visibility cycling: Visibility cycling. (line 6)
4978 * visible text, printing: Sparse trees. (line 39)
4979 * VM links: External links. (line 6)
4980 * WANDERLUST links: External links. (line 6)
4981 * windmove.el: Conflicts. (line 33)
4982 * workflow states as TODO keywords: Workflow states. (line 6)
4983 * XEmacs: Installation. (line 6)
4984 * XOXO export: XOXO export. (line 6)
4987 File: org, Node: Key Index, Prev: Index, Up: Top
4995 * ': CDLaTeX mode. (line 43)
4996 * +: Agenda commands. (line 126)
4997 * ,: Agenda commands. (line 118)
4998 * -: Agenda commands. (line 132)
4999 * .: Agenda commands. (line 94)
5000 * :: Agenda commands. (line 112)
5001 * <: Creating timestamps. (line 78)
5002 * <left>: Agenda commands. (line 91)
5003 * <RET> <1>: Agenda commands. (line 41)
5004 * <RET> <2>: Creating timestamps. (line 103)
5005 * <RET>: Built-in table editor.
5007 * <right>: Agenda commands. (line 86)
5008 * <SPC>: Agenda commands. (line 28)
5009 * <TAB> <1>: CDLaTeX mode. (line 23)
5010 * <TAB> <2>: Agenda commands. (line 35)
5011 * <TAB> <3>: Built-in table editor.
5013 * <TAB> <4>: Plain lists. (line 37)
5014 * <TAB>: Visibility cycling. (line 10)
5015 * > <1>: Agenda commands. (line 154)
5016 * >: Creating timestamps. (line 79)
5017 * ^: CDLaTeX mode. (line 33)
5018 * _: CDLaTeX mode. (line 33)
5019 * `: CDLaTeX mode. (line 39)
5020 * a: Agenda commands. (line 115)
5021 * C: Agenda commands. (line 194)
5022 * c: Agenda commands. (line 172)
5023 * C-#: Built-in table editor.
5025 * C-,: Agenda files. (line 18)
5026 * C-c !: Creating timestamps. (line 21)
5027 * C-c #: Checkboxes. (line 56)
5028 * C-c $: Moving subtrees. (line 10)
5029 * C-c %: Handling links. (line 80)
5030 * C-c &: Handling links. (line 84)
5031 * C-c ' <1>: Editing/debugging formulas.
5033 * C-c ': Built-in table editor.
5035 * C-c *: Built-in table editor.
5037 * C-c +: Built-in table editor.
5039 * C-c ,: Priorities. (line 18)
5040 * C-c -: Built-in table editor.
5042 * C-c .: Creating timestamps. (line 10)
5043 * C-c /: Sparse trees. (line 15)
5044 * C-c :: Enhancing text. (line 29)
5045 * C-c ;: Comment lines. (line 11)
5046 * C-c <: Creating timestamps. (line 25)
5047 * C-c <TAB>: Built-in table editor.
5049 * C-c =: Built-in table editor.
5051 * C-c >: Creating timestamps. (line 29)
5052 * C-c ? <1>: Editing/debugging formulas.
5054 * C-c ?: Built-in table editor.
5056 * C-c [: Agenda files. (line 12)
5057 * C-c \: Tag searches. (line 9)
5058 * C-c ]: Agenda files. (line 15)
5059 * C-c ^: Built-in table editor.
5061 * C-c `: Built-in table editor.
5063 * C-c a a: Weekly/Daily agenda. (line 9)
5064 * C-c a C: Agenda dispatcher. (line 29)
5065 * C-c a M: Matching headline tags.
5067 * C-c a m: Matching headline tags.
5069 * C-c a M: Tag searches. (line 14)
5070 * C-c a m: Tag searches. (line 10)
5071 * C-c a T: Global TODO list. (line 14)
5072 * C-c a t <1>: Global TODO list. (line 9)
5073 * C-c a t: TODO basics. (line 33)
5074 * C-c C-a: Visibility cycling. (line 31)
5075 * C-c C-b: Motion. (line 15)
5076 * C-c C-c <1>: The very busy C-c C-c key.
5078 * C-c C-c <2>: Processing LaTeX fragments.
5080 * C-c C-c <3>: Setting tags. (line 10)
5081 * C-c C-c <4>: Checkboxes. (line 38)
5082 * C-c C-c <5>: table.el. (line 6)
5083 * C-c C-c <6>: Editing/debugging formulas.
5085 * C-c C-c <7>: Built-in table editor.
5087 * C-c C-c: Plain lists. (line 74)
5088 * C-c C-d <1>: Agenda commands. (line 139)
5089 * C-c C-d: Creating timestamps. (line 37)
5090 * C-c C-e: Exporting. (line 19)
5091 * C-c C-e a: ASCII export. (line 9)
5092 * C-c C-e b: HTML export. (line 11)
5093 * C-c C-e c: iCalendar export. (line 20)
5094 * C-c C-e h: HTML export. (line 10)
5095 * C-c C-e I: iCalendar export. (line 15)
5096 * C-c C-e i: iCalendar export. (line 13)
5097 * C-c C-e t: Export options. (line 13)
5098 * C-c C-e v <1>: XOXO export. (line 11)
5099 * C-c C-e v: Sparse trees. (line 39)
5100 * C-c C-e v a: ASCII export. (line 13)
5101 * C-c C-e v b: HTML export. (line 14)
5102 * C-c C-e v h: HTML export. (line 14)
5103 * C-c C-e x: XOXO export. (line 10)
5104 * C-c C-f: Motion. (line 12)
5105 * C-c C-j: Motion. (line 21)
5106 * C-c C-l: Handling links. (line 27)
5107 * C-c C-n: Motion. (line 8)
5108 * C-c C-o <1>: Creating timestamps. (line 33)
5109 * C-c C-o: Handling links. (line 58)
5110 * C-c C-p: Motion. (line 9)
5111 * C-c C-q <1>: Editing/debugging formulas.
5113 * C-c C-q: Built-in table editor.
5115 * C-c C-r: Timeline. (line 13)
5116 * C-c C-s <1>: Agenda commands. (line 136)
5117 * C-c C-s: Creating timestamps. (line 48)
5118 * C-c C-t <1>: Clocking work time. (line 25)
5119 * C-c C-t: TODO basics. (line 13)
5120 * C-c C-u: Motion. (line 18)
5121 * C-c C-v: TODO basics. (line 26)
5122 * C-c C-w: Creating timestamps. (line 41)
5123 * C-c C-x C-a: ARCHIVE tag. (line 28)
5124 * C-c C-x C-b: Checkboxes. (line 39)
5125 * C-c C-x C-c: Agenda commands. (line 201)
5126 * C-c C-x C-d: Clocking work time. (line 33)
5127 * C-c C-x C-i: Clocking work time. (line 12)
5128 * C-c C-x C-k: Structure editing. (line 36)
5129 * C-c C-x C-l: Processing LaTeX fragments.
5131 * C-c C-x C-o: Clocking work time. (line 14)
5132 * C-c C-x C-r: Clocking work time. (line 40)
5133 * C-c C-x C-u: Dynamic blocks. (line 21)
5134 * C-c C-x C-w <1>: Built-in table editor.
5136 * C-c C-x C-w: Structure editing. (line 36)
5137 * C-c C-x C-x: Clocking work time. (line 29)
5138 * C-c C-x C-y <1>: Built-in table editor.
5140 * C-c C-x C-y: Structure editing. (line 43)
5141 * C-c C-x M-w <1>: Built-in table editor.
5143 * C-c C-x M-w: Structure editing. (line 40)
5144 * C-c C-y <1>: Clocking work time. (line 20)
5145 * C-c C-y: Creating timestamps. (line 66)
5146 * C-c l: Handling links. (line 9)
5147 * C-c {: CDLaTeX mode. (line 21)
5148 * C-c |: Built-in table editor.
5150 * C-c ~: table.el. (line 18)
5151 * C-TAB: ARCHIVE tag. (line 38)
5152 * C-u C-c $: Moving subtrees. (line 12)
5153 * C-u C-c .: Creating timestamps. (line 16)
5154 * C-u C-c =: Built-in table editor.
5156 * C-u C-c C-l: Handling links. (line 43)
5157 * C-u C-c C-x C-a: ARCHIVE tag. (line 31)
5158 * C-u C-c C-x C-u <1>: Dynamic blocks. (line 22)
5159 * C-u C-c C-x C-u: Clocking work time. (line 67)
5160 * D: Agenda commands. (line 68)
5161 * d: Agenda commands. (line 65)
5162 * f: Agenda commands. (line 44)
5163 * g: Agenda commands. (line 72)
5164 * H: Agenda commands. (line 198)
5165 * i: Agenda commands. (line 179)
5166 * I: Agenda commands. (line 159)
5167 * l: Agenda commands. (line 51)
5168 * L: Agenda commands. (line 32)
5169 * M: Agenda commands. (line 185)
5170 * M-<down>: Built-in table editor.
5172 * M-<left> <1>: Built-in table editor.
5174 * M-<left>: Structure editing. (line 18)
5175 * M-<RET> <1>: Plain lists. (line 42)
5176 * M-<RET>: Structure editing. (line 6)
5177 * M-<right> <1>: Built-in table editor.
5179 * M-<right>: Structure editing. (line 21)
5180 * M-<TAB> <1>: Completion. (line 10)
5181 * M-<TAB> <2>: Setting tags. (line 6)
5182 * M-<TAB>: Per file keywords. (line 17)
5183 * M-<up>: Built-in table editor.
5185 * M-S-<down> <1>: Built-in table editor.
5187 * M-S-<down> <2>: Plain lists. (line 59)
5188 * M-S-<down>: Structure editing. (line 33)
5189 * M-S-<left> <1>: Creating timestamps. (line 100)
5190 * M-S-<left> <2>: Built-in table editor.
5192 * M-S-<left> <3>: Plain lists. (line 65)
5193 * M-S-<left>: Structure editing. (line 24)
5194 * M-S-<RET> <1>: Checkboxes. (line 53)
5195 * M-S-<RET> <2>: Plain lists. (line 52)
5196 * M-S-<RET>: Structure editing. (line 15)
5197 * M-S-<right> <1>: Creating timestamps. (line 97)
5198 * M-S-<right> <2>: Built-in table editor.
5200 * M-S-<right> <3>: Plain lists. (line 65)
5201 * M-S-<right>: Structure editing. (line 27)
5202 * M-S-<up> <1>: Built-in table editor.
5204 * M-S-<up> <2>: Plain lists. (line 59)
5205 * M-S-<up>: Structure editing. (line 30)
5206 * mouse-1 <1>: Agenda commands. (line 35)
5207 * mouse-1 <2>: Creating timestamps. (line 82)
5208 * mouse-1: Handling links. (line 72)
5209 * mouse-2 <1>: Agenda commands. (line 35)
5210 * mouse-2: Handling links. (line 72)
5211 * mouse-3 <1>: Agenda commands. (line 28)
5212 * mouse-3: Handling links. (line 77)
5213 * n: Agenda commands. (line 19)
5214 * O: Agenda commands. (line 161)
5215 * o: Agenda commands. (line 59)
5216 * P: Agenda commands. (line 123)
5217 * p: Agenda commands. (line 20)
5218 * q: Agenda commands. (line 208)
5219 * r <1>: Agenda commands. (line 76)
5220 * r: Global TODO list. (line 20)
5221 * S: Agenda commands. (line 189)
5222 * s: Agenda commands. (line 83)
5223 * S-<down> <1>: Agenda commands. (line 132)
5224 * S-<down> <2>: Creating timestamps. (line 58)
5225 * S-<down> <3>: Priorities. (line 25)
5226 * S-<down>: Plain lists. (line 55)
5227 * S-<left> <1>: Agenda commands. (line 150)
5228 * S-<left> <2>: Creating timestamps. (line 53)
5229 * S-<left>: TODO basics. (line 20)
5230 * S-<RET>: Built-in table editor.
5232 * S-<right> <1>: Agenda commands. (line 142)
5233 * S-<right> <2>: Creating timestamps. (line 53)
5234 * S-<right>: TODO basics. (line 20)
5235 * S-<TAB> <1>: Built-in table editor.
5237 * S-<TAB>: Visibility cycling. (line 22)
5238 * S-<up> <1>: Agenda commands. (line 126)
5239 * S-<up> <2>: Creating timestamps. (line 58)
5240 * S-<up> <3>: Priorities. (line 25)
5241 * S-<up>: Plain lists. (line 55)
5242 * T: Agenda commands. (line 107)
5243 * t: Agenda commands. (line 103)
5244 * w: Agenda commands. (line 62)
5245 * x: Agenda commands. (line 211)
5246 * X: Agenda commands. (line 164)
5252 Node: Introduction
\x7f9683
5253 Node: Summary
\x7f10098
5254 Node: Installation
\x7f12365
5255 Node: Activation
\x7f13743
5256 Node: Feedback
\x7f14992
5257 Node: Document structure
\x7f15761
5258 Node: Outlines
\x7f16535
5259 Node: Headlines
\x7f17195
5260 Node: Visibility cycling
\x7f17818
5261 Ref: Visibility cycling-Footnote-1
\x7f19293
5262 Ref: Visibility cycling-Footnote-2
\x7f19351
5263 Node: Motion
\x7f19401
5264 Node: Structure editing
\x7f20185
5265 Node: Archiving
\x7f22294
5266 Node: ARCHIVE tag
\x7f22852
5267 Node: Moving subtrees
\x7f24645
5268 Node: Sparse trees
\x7f25686
5269 Ref: Sparse trees-Footnote-1
\x7f27665
5270 Ref: Sparse trees-Footnote-2
\x7f27757
5271 Node: Plain lists
\x7f27872
5272 Ref: Plain lists-Footnote-1
\x7f31397
5273 Ref: Plain lists-Footnote-2
\x7f31754
5274 Node: Tables
\x7f31936
5275 Node: Built-in table editor
\x7f32484
5276 Node: Narrow columns
\x7f40091
5277 Ref: Narrow columns-Footnote-1
\x7f42030
5278 Node: Table calculations
\x7f42076
5279 Node: Formula syntax
\x7f43396
5280 Ref: Formula syntax-Footnote-1
\x7f46301
5281 Node: Lisp formulas
\x7f46601
5282 Node: Column formulas
\x7f47390
5283 Node: Advanced features
\x7f49152
5284 Node: Named-field formulas
\x7f52406
5285 Node: Editing/debugging formulas
\x7f53046
5286 Node: Appetizer
\x7f54804
5287 Node: orgtbl-mode
\x7f55907
5288 Node: table.el
\x7f56398
5289 Node: Hyperlinks
\x7f57375
5290 Node: Link format
\x7f58080
5291 Node: Internal links
\x7f59373
5292 Ref: Internal links-Footnote-1
\x7f61362
5293 Node: Radio targets
\x7f61494
5294 Node: CamelCase links
\x7f62209
5295 Node: External links
\x7f62707
5296 Node: Handling links
\x7f64838
5297 Ref: Handling links-Footnote-1
\x7f69424
5298 Node: Search options
\x7f69661
5299 Ref: Search options-Footnote-1
\x7f71435
5300 Node: Custom searches
\x7f71516
5301 Node: Remember
\x7f72564
5302 Node: TODO items
\x7f76254
5303 Node: TODO basics
\x7f77236
5304 Node: TODO extensions
\x7f78763
5305 Node: Workflow states
\x7f79558
5306 Node: TODO types
\x7f80426
5307 Ref: TODO types-Footnote-1
\x7f82084
5308 Node: Per file keywords
\x7f82166
5309 Ref: Per file keywords-Footnote-1
\x7f83620
5310 Node: Priorities
\x7f83821
5311 Node: Breaking down tasks
\x7f85065
5312 Ref: Breaking down tasks-Footnote-1
\x7f85585
5313 Node: Checkboxes
\x7f85681
5314 Node: Timestamps
\x7f88490
5315 Node: Time stamps
\x7f88880
5316 Node: Creating timestamps
\x7f91977
5317 Node: Progress logging
\x7f95323
5318 Node: Closing items
\x7f95853
5319 Node: Clocking work time
\x7f96648
5320 Ref: Clocking work time-Footnote-1
\x7f100084
5321 Node: Tags
\x7f100210
5322 Node: Tag inheritance
\x7f100972
5323 Node: Setting tags
\x7f101909
5324 Ref: Setting tags-Footnote-1
\x7f105039
5325 Ref: Setting tags-Footnote-2
\x7f105151
5326 Node: Tag searches
\x7f105231
5327 Node: Agenda views
\x7f106440
5328 Node: Agenda files
\x7f107984
5329 Ref: Agenda files-Footnote-1
\x7f108944
5330 Ref: Agenda files-Footnote-2
\x7f109093
5331 Node: Agenda dispatcher
\x7f109285
5332 Node: Weekly/Daily agenda
\x7f111401
5333 Node: Categories
\x7f112536
5334 Node: Time-of-day specifications
\x7f113184
5335 Node: Calendar/Diary integration
\x7f115160
5336 Node: Sorting of agenda items
\x7f116537
5337 Node: Global TODO list
\x7f117369
5338 Node: Matching headline tags
\x7f119420
5339 Node: Timeline
\x7f120363
5340 Node: Agenda commands
\x7f121236
5341 Node: Embedded LaTeX
\x7f127080
5342 Ref: Embedded LaTeX-Footnote-1
\x7f128172
5343 Node: Math symbols
\x7f128362
5344 Node: Subscripts and Superscripts
\x7f129127
5345 Node: LaTeX fragments
\x7f129971
5346 Node: Processing LaTeX fragments
\x7f132040
5347 Node: CDLaTeX mode
\x7f132986
5348 Ref: CDLaTeX mode-Footnote-1
\x7f135470
5349 Node: Exporting
\x7f135618
5350 Node: ASCII export
\x7f136932
5351 Node: HTML export
\x7f138222
5352 Node: XOXO export
\x7f141058
5353 Node: iCalendar export
\x7f141497
5354 Node: Text interpretation
\x7f143320
5355 Node: Comment lines
\x7f143799
5356 Node: Enhancing text
\x7f144270
5357 Node: Export options
\x7f145962
5358 Node: Publishing
\x7f147629
5359 Ref: Publishing-Footnote-1
\x7f148425
5360 Node: Configuration
\x7f148621
5361 Node: Project alist
\x7f149339
5362 Node: Sources and destinations
\x7f150405
5363 Node: Selecting files
\x7f150952
5364 Node: Publishing action
\x7f151700
5365 Node: Publishing options
\x7f152815
5366 Node: Publishing links
\x7f154967
5367 Node: Project page index
\x7f156480
5368 Node: Sample configuration
\x7f157258
5369 Node: Simple example
\x7f157750
5370 Node: Complex example
\x7f158423
5371 Node: Triggering publication
\x7f160499
5372 Node: Miscellaneous
\x7f161184
5373 Node: Completion
\x7f161818
5374 Node: Customization
\x7f162814
5375 Node: In-buffer settings
\x7f163399
5376 Node: The very busy C-c C-c key
\x7f166630
5377 Node: Clean view
\x7f168274
5378 Node: TTY keys
\x7f170851
5379 Node: Interaction
\x7f172460
5380 Node: Cooperation
\x7f172857
5381 Node: Conflicts
\x7f174724
5382 Node: Bugs
\x7f176316
5383 Node: Extensions and Hacking
\x7f177939
5384 Node: Extensions
\x7f178425
5385 Node: Dynamic blocks
\x7f179995
5386 Node: History and Acknowledgments
\x7f181915
5387 Node: Index
\x7f186719
5388 Node: Key Index
\x7f209924