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 5.02).
10 Copyright (C) 2004, 2005, 2006, 2007 Free Software Foundation
12 Permission is granted to copy, distribute and/or modify this
13 document under the terms of the GNU Free Documentation License,
14 Version 1.1 or any later version published by the Free Software
15 Foundation; with no Invariant Sections, with the Front-Cover texts
16 being "A GNU Manual," and with the Back-Cover Texts as in (a)
17 below. A copy of the license is included in the section entitled
18 "GNU Free Documentation License."
20 (a) The FSF's Back-Cover Text is: "You have freedom to copy and
21 modify this GNU Manual, like GNU software. Copies published by
22 the Free Software Foundation raise funds for GNU development."
25 File: org, Node: Top, Next: Introduction, Prev: (dir), Up: (dir)
30 This manual is for Org-mode (version 5.02).
32 Copyright (C) 2004, 2005, 2006, 2007 Free Software Foundation
34 Permission is granted to copy, distribute and/or modify this
35 document under the terms of the GNU Free Documentation License,
36 Version 1.1 or any later version published by the Free Software
37 Foundation; with no Invariant Sections, with the Front-Cover texts
38 being "A GNU Manual," and with the Back-Cover Texts as in (a)
39 below. A copy of the license is included in the section entitled
40 "GNU Free Documentation License."
42 (a) The FSF's Back-Cover Text is: "You have freedom to copy and
43 modify this GNU Manual, like GNU software. Copies published by
44 the Free Software Foundation raise funds for GNU development."
48 * Introduction:: Getting started
49 * Document structure:: A tree works like your brain
50 * Tables:: Pure magic for quick formatting
51 * Hyperlinks:: Notes in context
52 * TODO items:: Every tree branch can be a TODO item
53 * Tags:: Tagging headlines and matching sets of tags
54 * Properties and columns::
55 * Timestamps:: Assign date and time to items
56 * Agenda views:: Collecting information into views
57 * Embedded LaTeX:: LaTeX fragments and formulas
58 * Exporting:: Sharing and publishing of notes
59 * Publishing:: Create a web site of linked Org-mode files
60 * Miscellaneous:: All the rest which did not fit elsewhere
61 * Extensions and Hacking:: It is possible to write add-on code
62 * History and Acknowledgments:: How Org-mode came into being
63 * Index:: The fast road to specific information
64 * Key Index:: Key bindings and where they are described
66 --- The Detailed Node Listing ---
70 * Summary:: Brief summary of what Org-mode does
71 * Installation:: How to install a downloaded version of Org-mode
72 * Activation:: How to activate Org-mode for certain buffers.
73 * Feedback:: Bug reports, ideas, patches etc.
77 * Outlines:: Org-mode is based on outline-mode
78 * Headlines:: How to typeset org-tree headlines
79 * Visibility cycling:: Show and hide, much simplified
80 * Motion:: Jumping to other headlines
81 * Structure editing:: Changing sequence and level of headlines
82 * Archiving:: Move done task trees to a different place
83 * Sparse trees:: Matches embedded in context
84 * Plain lists:: Additional structure within an entry
85 * Drawers:: Tucking stuff away
86 * orgstruct-mode:: Structure editing outside Org-mode
90 * ARCHIVE tag:: Marking a tree as inactive
91 * Moving subtrees:: Moving a tree to an archive file
95 * Built-in table editor:: Simple tables
96 * Narrow columns:: Stop wasting space in tables
97 * Column groups:: Grouping to trigger vertical lines
98 * orgtbl-mode:: The table editor as minor mode
99 * The spreadsheet:: The table editor has spreadsheet capabilities.
103 * References:: How to refer to another field or range
104 * Formula syntax for Calc:: Using Calc to compute stuff
105 * Formula syntax for Lisp:: Writing formulas in Emacs Lisp
106 * Field formulas:: Formulas valid for a single field
107 * Column formulas:: Formulas valid for an entire column
108 * Editing and debugging formulas:: Fixing formulas
109 * Updating the table:: Recomputing all dependent fields
110 * Advanced features:: Field names, parameters and automatic recalc
114 * Link format:: How links in Org-mode are formatted
115 * Internal links:: Links to other places in the current file
116 * External links:: URL-like links to the world
117 * Handling links:: Creating, inserting and following
118 * Link abbreviations:: Shortcuts for writing complex links
119 * Search options:: Linking to a specific location
120 * Custom searches:: When the default search is not enough
121 * Remember:: Org-trees store quick notes
125 * Radio targets:: Make targets trigger links in plain text.
129 * Setting up remember:: Some code for .emacs to get things going
130 * Remember templates:: Define the outline of different note types
131 * Storing notes:: Directly get the note to where it belongs
135 * TODO basics:: Marking and displaying TODO entries
136 * TODO extensions:: Workflow and assignments
137 * Priorities:: Some things are more important than others
138 * Breaking down tasks:: Splitting a task into manageable pieces
139 * Checkboxes:: Tick-off lists
141 Extended use of TODO keywords
143 * Workflow states:: From TODO to DONE in steps
144 * TODO types:: I do this, Fred the rest
145 * Multiple sets in one file:: Mixing it all, and still finding your way
146 * Per file keywords:: Different files, different requirements
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
154 Properties and Columns
156 * Property syntax:: How properties are spelled out
157 * Special properties:: Access to other Org-mode features
158 * Property searches:: Matching property values
159 * Column view:: Tabular viewing and editing
160 * Property API:: Properties for Lisp programmers
164 * Defining columns:: The COLUMNS format property
165 * Using column view:: How to create and use column view
169 * Scope of column definitions::
170 * Column attributes::
174 * Time stamps:: Assigning a time to a tree entry
175 * Creating timestamps:: Commands which insert timestamps
176 * Deadlines and scheduling:: Planning your work
177 * Progress logging:: Documenting when what work was done.
181 * The date/time prompt:: How org-mode helps you entering date and time
182 * Custom time format:: Making dates look differently
184 Deadlines and Scheduling
186 * Inserting deadline/schedule::
191 * Closing items:: When was this entry marked DONE?
192 * Tracking TODO state changes:: When did the status change?
193 * Clocking work time:: When exactly did you work on this item?
197 * Agenda files:: Files being searched for agenda information
198 * Agenda dispatcher:: Keyboard access to agenda views
199 * Built-in agenda views:: What is available out of the box?
200 * Presentation and sorting:: How agenda items are prepared for display
201 * Agenda commands:: Remote editing of org trees
202 * Custom agenda views:: Defining special searches and views
204 The built-in agenda views
206 * Weekly/Daily agenda:: The calendar page with current tasks
207 * Global TODO list:: All unfinished action items
208 * Matching tags and properties:: Structured information with fine-tuned search
209 * Timeline:: Time-sorted view for single file
210 * Stuck projects:: Find projects you need to review
212 Presentation and sorting
214 * Categories:: Not all tasks are equal
215 * Time-of-day specifications:: How the agenda knows the time
216 * Sorting of agenda items:: The order of things
220 * Storing searches:: Type once, use often
221 * Block agenda:: All the stuff you need in a single buffer
222 * Setting Options:: Changing the rules
223 * Exporting Agenda Views:: Writing agendas to files.
224 * Extracting Agenda Information for other programs::
228 * Math symbols:: TeX macros for symbols and Greek letters
229 * Subscripts and Superscripts:: Simple syntax for raising/lowering text
230 * LaTeX fragments:: Complex formulas made easy
231 * Processing LaTeX fragments:: Previewing LaTeX processing
232 * CDLaTeX mode:: Speed up entering of formulas
236 * ASCII export:: Exporting to plain ASCII
237 * HTML export:: Exporting to HTML
238 * XOXO export:: Exporting to XOXO
239 * iCalendar export:: Exporting in iCalendar format
240 * Text interpretation:: How the exporter looks at the file
244 * Export commands:: How to invoke HTML export
245 * Quoting HTML tags:: Using direct HTML in Org-mode
246 * Links:: How hyperlinks get transferred to HTML
247 * Images:: To inline or not to inline?
248 * CSS support:: Style specifications
250 Text interpretation by the exporter
252 * Comment lines:: Some lines will not be exported
253 * Initial text:: Text before the first headline
254 * Footnotes:: Numbers like [1]
255 * Enhancing text:: Subscripts, symbols and more
256 * Export options:: How to influence the export settings
260 * Configuration:: Defining projects
261 * Sample configuration:: Example projects
262 * Triggering publication:: Publication commands
266 * Project alist:: The central configuration variable
267 * Sources and destinations:: From here to there
268 * Selecting files:: What files are part of the project?
269 * Publishing action:: Setting the function doing the publishing
270 * Publishing options:: Tweaking HTML export
271 * Publishing links:: Which links keep working after publishing?
272 * Project page index:: Publishing a list of project files
276 * Simple example:: One-component publishing
277 * Complex example:: A multi-component publishing example
281 * Completion:: M-TAB knows what you need
282 * Customization:: Adapting Org-mode to your taste
283 * In-buffer settings:: Overview of the #+KEYWORDS
284 * The very busy C-c C-c key:: When in doubt, press C-c C-c
285 * Clean view:: Getting rid of leading stars in the outline
286 * TTY keys:: Using Org-mode on a tty
287 * Interaction:: Other Emacs packages
288 * Bugs:: Things which do not work perfectly
290 Interaction with other packages
292 * Cooperation:: Packages Org-mode cooperates with
293 * Conflicts:: Packages that lead to conflicts
295 Extensions, Hooks and Hacking
297 * Extensions:: Existing 3rd-part extensions
298 * Tables in arbitrary syntax:: Orgtbl for LaTeX and other programs
299 * Dynamic blocks:: Automatically filled blocks
300 * Special agenda views:: Customized views
301 * Using the property API:: Writing programs that use entry properties
303 Tables in arbitrary syntax
305 * Radio tables:: Sending and receiving
306 * A LaTeX example:: Step by step, almost a tutorial
307 * Translator functions:: Copy and modify
310 File: org, Node: Introduction, Next: Document structure, Prev: Top, Up: Top
317 * Summary:: Brief summary of what Org-mode does
318 * Installation:: How to install a downloaded version of Org-mode
319 * Activation:: How to activate Org-mode for certain buffers.
320 * Feedback:: Bug reports, ideas, patches etc.
323 File: org, Node: Summary, Next: Installation, Prev: Introduction, Up: Introduction
328 Org-mode is a mode for keeping notes, maintaining TODO lists, and doing
329 project planning with a fast and effective plain-text system.
331 Org-mode develops organizational tasks around NOTES files that
332 contain lists or information about projects as plain text. Org-mode is
333 implemented on top of outline-mode, which makes it possible to keep the
334 content of large files well structured. Visibility cycling and
335 structure editing help to work with the tree. Tables are easily created
336 with a built-in table editor. Org-mode supports TODO items, deadlines,
337 time stamps, and scheduling. It dynamically compiles entries into an
338 agenda that utilizes and smoothly integrates much of the Emacs calendar
339 and diary. Plain text URL-like links connect to websites, emails,
340 Usenet messages, BBDB entries, and any files related to the projects.
341 For printing and sharing of notes, an Org-mode file can be exported as a
342 structured ASCII file, as HTML, or (todo and agenda items only) as an
343 iCalendar file. It can also serve as a publishing tool for a set of
346 An important design aspect that distinguishes Org-mode from for
347 example Planner/Muse is that it encourages to store every piece of
348 information only once. In Planner, you have project pages, day pages
349 and possibly other files, duplicating some information such as tasks.
350 In Org-mode, you only have notes files. In your notes you mark entries
351 as tasks, label them with tags and timestamps. All necessary lists
352 like a schedule for the day, the agenda for a meeting, tasks lists
353 selected by tags etc are created dynamically when you need them.
355 Org-mode keeps simple things simple. When first fired up, it should
356 feel like a straightforward, easy to use outliner. Complexity is not
357 imposed, but a large amount of functionality is available when you need
358 it. Org-mode is a toolbox and can be used in different ways, for
361 * outline extension with visibility cycling and structure editing
362 * ASCII system and table editor for taking structured notes
363 * ASCII table editor with spreadsheet-like capabilities
365 * full agenda and planner with deadlines and work scheduling
366 * environment to implement David Allen's GTD system
367 * a basic database application
368 * simple hypertext system, with HTML export
369 * publishing tool to create a set of interlinked webpages
371 Org-mode's automatic, context sensitive table editor with spreadsheet
372 capabilities can be integrated into any major mode by activating the
373 minor Orgtbl-mode. Using a translation step, it can be used to maintain
374 tables in arbitrary file types, for example in LaTeX. The structure
375 editing and list creation capabilities can be used outside Org-mode with
376 the minor Orgstruct-mode.
378 There is a website for Org-mode which provides links to the newest
379 version of Org-mode, as well as additional information, frequently asked
380 questions (FAQ), links to tutorials etc. This page is located at
381 `http://www.astro.uva.nl/~dominik/Tools/org/'.
384 File: org, Node: Installation, Next: Activation, Prev: Summary, Up: Introduction
389 Important: If Org-mode is part of the Emacs distribution or an XEmacs
390 package, please skip this section and go directly to *Note Activation::.
392 If you have downloaded Org-mode from the Web, you must take the
393 following steps to install it: Go into the Org-mode distribution
394 directory and edit the top section of the file `Makefile'. You must
395 set the name of the Emacs binary (likely either `emacs' or `xemacs'),
396 and the paths to the directories where local Lisp and Info files are
397 kept. If you don't have access to the system-wide directories, create
398 your own two directories for these files, enter them into the Makefile,
399 and make sure Emacs finds the Lisp files by adding the following line
402 (setq load-path (cons "~/path/to/lispdir" load-path))
404 XEmacs users now need to install the file `noutline.el' from the
405 `xemacs' subdirectory of the Org-mode distribution. Use the command:
407 make install-noutline
409 Now byte-compile and install the Lisp files with the shell commands:
414 If you want to install the info documentation, use this command:
418 Then add to `.emacs':
420 ;; This line only if org-mode is not part of the X/Emacs distribution.
421 (require 'org-install)
424 File: org, Node: Activation, Next: Feedback, Prev: Installation, Up: Introduction
429 Add the following lines to your `.emacs' file. The last two lines
430 define _global_ keys for the commands `org-store-link' and `org-agenda'
431 - please choose suitable keys yourself.
433 ;; The following lines are always needed. Choose your own keys.
434 (add-to-list 'auto-mode-alist '("\\.org$" . org-mode))
435 (define-key global-map "\C-cl" 'org-store-link)
436 (define-key global-map "\C-ca" 'org-agenda)
438 Furthermore, you must activate `font-lock-mode' in org-mode buffers,
439 because significant functionality depends on font-locking being active.
440 You can do this with either one of the following two lines (XEmacs
441 user must use the second option):
442 (global-font-lock-mode 1) ; for all buffers
443 (add-hook 'org-mode-hook 'turn-on-font-lock) ; org-mode buffers only
445 With this setup, all files with extension `.org' will be put into
446 Org-mode. As an alternative, make the first line of a file look like
449 MY PROJECTS -*- mode: org; -*-
451 which will select Org-mode for this buffer no matter what the file's
452 name is. See also the variable `org-insert-mode-line-in-empty-file'.
455 File: org, Node: Feedback, Prev: Activation, Up: Introduction
460 If you find problems with Org-mode, or if you have questions, remarks,
461 or ideas about it, please contact the maintainer Carsten Dominik at
462 <dominik at science dot uva dot nl>.
464 For bug reports, please provide as much information as possible,
465 including the version information of Emacs (`C-h v emacs-version
466 <RET>') and Org-mode (`C-h v org-version <RET>'), as well as the
467 Org-mode related setup in `.emacs'. If an error occurs, a backtrace
468 can be very useful (see below on how to create one). Often a small
469 example file helps, along with clear information about:
471 1. What exactly did you do?
473 2. What did you expect to happen?
475 3. What happened instead?
476 Thank you for helping to improve this mode.
478 How to create a useful backtrace
479 ................................
481 If working with Org-mode produces an error with a message you don't
482 understand, you may have hit a bug. The best way to report this is by
483 providing, in addition to what was mentioned above, a _Backtrace_.
484 This is information from the built-in debugger about where and how the
485 error occurred. Here is how to produce a useful backtrace:
487 1. Start a fresh Emacs or XEmacs, and make sure that it will load the
488 original Lisp code in `org.el' instead of the compiled version in
489 `org.elc'. The backtrace contains much more information if it is
490 produced with uncompiled code. To do this, either rename `org.elc'
491 to something else before starting Emacs, or ask Emacs explicitly
492 to load `org.el' by using the command line
493 emacs -l /path/to/org.el
495 2. Go to the `Options' menu and select `Enter Debugger on Error'
496 (XEmacs has this option in the `Troubleshooting' sub-menu).
498 3. Do whatever you have to do to hit the error. Don't forget to
499 document the steps you take.
501 4. When you hit the error, a `*Backtrace*' buffer will appear on the
502 screen. Save this buffer to a file (for example using `C-x C-w')
503 and attach it to your bug report.
506 File: org, Node: Document structure, Next: Tables, Prev: Introduction, Up: Top
511 Org-mode is based on outline mode and provides flexible commands to
512 edit the structure of the document.
516 * Outlines:: Org-mode is based on outline-mode
517 * Headlines:: How to typeset org-tree headlines
518 * Visibility cycling:: Show and hide, much simplified
519 * Motion:: Jumping to other headlines
520 * Structure editing:: Changing sequence and level of headlines
521 * Archiving:: Move done task trees to a different place
522 * Sparse trees:: Matches embedded in context
523 * Plain lists:: Additional structure within an entry
524 * Drawers:: Tucking stuff away
525 * orgstruct-mode:: Structure editing outside Org-mode
528 File: org, Node: Outlines, Next: Headlines, Prev: Document structure, Up: Document structure
533 Org-mode is implemented on top of outline-mode. Outlines allow to
534 organize a document in a hierarchical structure, which (at least for
535 me) is the best representation of notes and thoughts. Overview over
536 this structure is achieved by folding (hiding) large parts of the
537 document to show only the general document structure and the parts
538 currently being worked on. Org-mode greatly simplifies the use of
539 outlines by compressing the entire show/hide functionality into a
540 single command `org-cycle', which is bound to the <TAB> key.
543 File: org, Node: Headlines, Next: Visibility cycling, Prev: Outlines, Up: Document structure
548 Headlines define the structure of an outline tree. The headlines in
549 Org-mode start with one or more stars, on the left margin(1). For
559 * Another top level headline
561 Some people find the many stars too noisy and would prefer an outline
562 that has whitespace followed by a single star as headline starters.
563 *Note Clean view:: describes a setup to realize this.
565 An empty line after the end of a subtree is considered part of it and
566 will be hidden when the subtree is folded. However, if you leave at
567 least two empty lines, one empty line will remain visible after folding
568 the subtree, in order to structure the collapsed view. See the
569 variable `org-cycle-separator-lines' for modifying this behavior.
571 ---------- Footnotes ----------
573 (1) See the variable `org-special-ctrl-a' to configure special
574 behavior of `C-a' in headlines.
577 File: org, Node: Visibility cycling, Next: Motion, Prev: Headlines, Up: Document structure
579 2.3 Visibility cycling
580 ======================
582 Outlines make it possible to hide parts of the text in the buffer.
583 Org-mode uses just two commands, bound to <TAB> and `S-<TAB>' to change
584 the visibility in the buffer.
587 _Subtree cycling_: Rotate current subtree among the states
589 ,-> FOLDED -> CHILDREN -> SUBTREE --.
590 '-----------------------------------'
592 The cursor must be on a headline for this to work(1). When the
593 cursor is at the beginning of the buffer and the first line is not
594 a headline, then <TAB> actually runs global cycling (see
595 below)(2). Also when called with a prefix argument (`C-u <TAB>'),
596 global cycling is invoked.
600 _Global cycling_: Rotate the entire buffer among the states
602 ,-> OVERVIEW -> CONTENTS -> SHOW ALL --.
603 '--------------------------------------'
605 When `S-<TAB>' is called with a numerical prefix N, the CONTENTS
606 view up to headlines of level N will be shown. Note that inside
607 tables, `S-<TAB>' jumps to the previous field.
613 Reveal context around point, showing the current entry, the
614 following heading and the hierarchy above. Useful for working
615 near a location exposed by a sparse tree command (*note Sparse
616 trees::) or an agenda command (*note Agenda commands::). With
617 prefix arg show, on each level, all sibling headings.
620 Show the current subtree in an indirect buffer(3). With numerical
621 prefix ARG, go up to this level and then take that tree. If ARG is
622 negative, go up that many levels. With `C-u' prefix, do not remove
623 the previously used indirect buffer.
625 When Emacs first visits an Org-mode file, the global state is set to
626 OVERVIEW, i.e. only the top level headlines are visible. This can be
627 configured through the variable `org-startup-folded', or on a per-file
628 basis by adding one of the following lines anywhere in the buffer:
634 ---------- Footnotes ----------
636 (1) see, however, the option `org-cycle-emulate-tab'.
638 (2) see the option `org-cycle-global-at-bob'.
640 (3) The indirect buffer (*note Indirect Buffers: (emacs)Indirect
641 Buffers.) will contain the entire buffer, but will be narrowed to the
642 current tree. Editing the indirect buffer will also change the
643 original buffer, but without affecting visibility in that buffer.
646 File: org, Node: Motion, Next: Structure editing, Prev: Visibility cycling, Up: Document structure
651 The following commands jump to other headlines in the buffer.
660 Next heading same level.
663 Previous heading same level.
666 Backward to higher level heading.
669 Jump to a different place without changing the current outline
670 visibility. Shows the document structure in a temporary buffer,
671 where you can use the following keys to find your destination:
672 <TAB> Cycle visibility.
673 <down> / <up> Next/previous visible headline.
674 n / p Next/previous visible headline.
675 f / b Next/previous headline same level.
678 <RET> Select this location.
681 File: org, Node: Structure editing, Next: Archiving, Prev: Motion, Up: Document structure
683 2.5 Structure editing
684 =====================
687 Insert new heading with same level as current. If the cursor is
688 in a plain list item, a new item is created (*note Plain lists::).
689 To force creation of a new headline, use a prefix arg, or first
690 press <RET> to get to the beginning of the next line. When this
691 command is used in the middle of a line, the line is split and the
692 rest of the line becomes the new headline. If the command is used
693 at the beginning of a headline, the new headline is created before
694 the current line. If at the beginning of any other line, the
695 content of that line is made the new heading. If the command is
696 used at the end of a folded subtree (i.e. behind the ellipses at
697 the end of a headline), then a headline like the current one will
698 be inserted after the end of the subtree.
701 Insert new TODO entry with same level as current heading.
704 Promote current heading by one level.
707 Demote current heading by one level.
710 Promote the current subtree by one level.
713 Demote the current subtree by one level.
716 Move subtree up (swap with previous subtree of same level).
719 Move subtree down (swap with next subtree of same level).
723 Kill subtree, i.e. remove it from buffer but save in kill ring.
726 Copy subtree to kill ring.
729 Yank subtree from kill ring. This does modify the level of the
730 subtree to make sure the tree fits in nicely at the yank position.
731 The yank level can also be specified with a prefix arg, or by
732 yanking after a headline marker like `****'.
735 Sort same-level entries. When there is an active region, all
736 entries in the region will be sorted. Otherwise the children of
737 the current headline are sorted. The command prompts for the
738 sorting method, which can be alphabetically, numerically, by time
739 (using the first time stamp in each entry), and each of these in
740 reverse order. With a `C-u' prefix, sorting will be
741 case-sensitive. With two `C-u C-u' prefixes, duplicate entries
742 will also be removed.
744 When there is an active region (transient-mark-mode), promotion and
745 demotion work on all headlines in the region. To select a region of
746 headlines, it is best to place both point and mark at the beginning of a
747 line, mark at the beginning of the first headline, and point at the line
748 just after the last headline to change. Note that when the cursor is
749 inside a table (*note Tables::), the Meta-Cursor keys have different
753 File: org, Node: Archiving, Next: Sparse trees, Prev: Structure editing, Up: Document structure
758 When a project represented by a (sub)tree is finished, you may want to
759 move the tree out of the way and to stop it from contributing to the
760 agenda. Org-mode knows two ways of archiving. You can mark a tree with
761 the ARCHIVE tag, or you can move an entire (sub)tree to a different
766 * ARCHIVE tag:: Marking a tree as inactive
767 * Moving subtrees:: Moving a tree to an archive file
770 File: org, Node: ARCHIVE tag, Next: Moving subtrees, Prev: Archiving, Up: Archiving
772 2.6.1 The ARCHIVE tag
773 ---------------------
775 A headline that is marked with the ARCHIVE tag (*note Tags::) stays at
776 its location in the outline tree, but behaves in the following way:
777 - It does not open when you attempt to do so with a visibility
778 cycling command (*note Visibility cycling::). You can force
779 cycling archived subtrees with `C-<TAB>', or by setting the option
780 `org-cycle-open-archived-trees'. Also normal outline commands like
781 `show-all' will open archived subtrees.
783 - During sparse tree construction (*note Sparse trees::), matches in
784 archived subtrees are not exposed, unless you configure the option
785 `org-sparse-tree-open-archived-trees'.
787 - During agenda view construction (*note Agenda views::), the
788 content of archived trees is ignored unless you configure the
789 option `org-agenda-skip-archived-trees'.
791 - Archived trees are not exported (*note Exporting::), only the
792 headline is. Configure the details using the variable
793 `org-export-with-archived-trees'.
795 The following commands help managing the ARCHIVE tag:
798 Toggle the ARCHIVE tag for the current headline. When the tag is
799 set, the headline changes to a shadowish face, and the subtree
803 Check if any direct children of the current headline should be
804 archived. To do this, each subtree is checked for open TODO
805 entries. If none are found, the command offers to set the ARCHIVE
806 tag for the child. If the cursor is _not_ on a headline when this
807 command is invoked, the level 1 trees will be checked.
810 Cycle a tree even if it is tagged with ARCHIVE.
813 File: org, Node: Moving subtrees, Prev: ARCHIVE tag, Up: Archiving
815 2.6.2 Moving subtrees
816 ---------------------
818 Once an entire project is finished, you may want to move it to a
819 different location, either in the current file, or even in a different
820 file, the archive file.
823 Archive the subtree starting at the cursor position to the location
824 given by `org-archive-location'.
827 Check if any direct children of the current headline could be
828 moved to the archive. To do this, each subtree is checked for
829 open TODO entries. If none are found, the command offers to move
830 it to the archive location. If the cursor is _not_ on a headline
831 when this command is invoked, the level 1 trees will be checked.
833 The default archive location is a file in the same directory as the
834 current file, with the name derived by appending `_archive' to the
835 current file name. For information and examples on how to change this,
836 see the documentation string of the variable `org-archive-location'.
837 There is also an in-buffer option for setting this variable, for example
841 You may have several such lines in the buffer, they will then be valid
842 for the entries following the line (the first will also apply to any
846 File: org, Node: Sparse trees, Next: Plain lists, Prev: Archiving, Up: Document structure
851 An important feature of Org-mode is the ability to construct _sparse
852 trees_ for selected information in an outline tree. A sparse tree
853 means that the entire document is folded as much as possible, but the
854 selected information is made visible along with the headline structure
855 above it(1). Just try it out and you will see immediately how it works.
857 Org-mode contains several commands creating such trees. The most
858 basic one is `org-occur':
861 Occur. Prompts for a regexp and shows a sparse tree with all
862 matches. If the match is in a headline, the headline is made
863 visible. If the match is in the body of an entry, headline and
864 body are made visible. In order to provide minimal context, also
865 the full hierarchy of headlines above the match is shown, as well
866 as the headline following the match. Each match is also
867 highlighted; the highlights disappear when the buffer is changes
868 an editing command, or by pressing `C-c C-c'. When called with a
869 `C-u' prefix argument, previous highlights are kept, so several
870 calls to this command can be stacked.
871 For frequently used sparse trees of specific search strings, you can
872 use the variable `org-agenda-custom-commands' to define fast keyboard
873 access to specific sparse trees. These commands will then be
874 accessible through the agenda dispatcher (*note Agenda dispatcher::).
877 (setq org-agenda-custom-commands
878 '(("f" occur-tree "FIXME")))
880 will define the key `C-c a f' as a shortcut for creating a sparse tree
881 matching the string `FIXME'.
883 Other commands use sparse trees as well. For example `C-c C-v'
884 creates a sparse TODO tree (*note TODO basics::).
886 To print a sparse tree, you can use the Emacs command
887 `ps-print-buffer-with-faces' which does not print invisible parts of
888 the document (2). Or you can use the command `C-c C-e v' to export
889 only the visible part of the document and print the resulting file.
891 ---------- Footnotes ----------
893 (1) See also the variables `org-show-hierarchy-above',
894 `org-show-following-heading', and `org-show-siblings' for detailed
895 control on how much context is shown around each match.
897 (2) This does not work under XEmacs, because XEmacs uses selective
898 display for outlining, not text properties.
901 File: org, Node: Plain lists, Next: Drawers, Prev: Sparse trees, Up: Document structure
906 Within an entry of the outline tree, hand-formatted lists can provide
907 additional structure. They also provide a way to create lists of
908 checkboxes (*note Checkboxes::). Org-mode supports editing such lists,
909 and the HTML exporter (*note Exporting::) does parse and format them.
911 Org-mode knows ordered and unordered lists. Unordered list items
912 start with `-', `+', or `*'(1) as bullets. Ordered list items start
913 with `1.' or `1)'. Items belonging to the same list must have the same
914 indentation on the first line. In particular, if an ordered list
915 reaches number `10.', then the 2-digit numbers must be written
916 left-aligned with the other numbers in the list. Indentation also
917 determines the end of a list item. It ends before the next line that
918 is indented like the bullet/number, or less. Empty lines are part of
919 the previous item, so you can have several paragraphs in one item. If
920 you would like an empty line to terminate all currently open plain
921 lists, configure the variable `org-empty-line-terminates-plain-lists'.
925 My favorite scenes are (in this order)
926 1. The attack of the Rohirrim
927 2. Eowyns fight with the witch king
928 + this was already my favorite scene in the book
929 + I really like Miranda Otto.
930 3. Peter Jackson being shot by Legolas
932 He makes a really funny face when it happens.
933 But in the end, not individual scenes matter but the film as a whole.
935 Org-mode supports these lists by tuning filling and wrapping
936 commands to deal with them correctly(2).
938 The following commands act on items when the cursor is in the first
939 line of an item (the line with the bullet or number).
942 Items can be folded just like headline levels if you set the
943 variable `org-cycle-include-plain-lists'. The level of an item is
944 then given by the indentation of the bullet/number. Items are
945 always subordinate to real headlines, however; the hierarchies
946 remain completely separated.
948 If `org-cycle-include-plain-lists' has not been set, <TAB> fixes
949 the indentation of the curent line in a heuristic way.
952 Insert new item at current level. With prefix arg, force a new
953 heading (*note Structure editing::). If this command is used in
954 the middle of a line, the line is _split_ and the rest of the line
955 becomes the new item. If this command is executed in the
956 _whitespace before a bullet or number_, the new item is created
957 _before_ the current item. If the command is executed in the
958 white space before the text that is part of an item but does not
959 contain the bullet, a bullet is added to the current line.
962 Insert a new item with a checkbox (*note Checkboxes::).
966 Jump to the previous/next item in the current list.
970 Move the item including subitems up/down (swap with previous/next
971 item of same indentation). If the list is ordered, renumbering is
976 Decrease/increase the indentation of the item, including subitems.
977 Initially, the item tree is selected based on current indentation.
978 When these commands are executed several times in direct
979 succession, the initially selected region is used, even if the new
980 indentation would imply a different hierarchy. To use the new
981 hierarchy, break the command chain with a cursor motion or so.
984 If there is a checkbox (*note Checkboxes::) in the item line,
985 toggle the state of the checkbox. If not, make this command makes
986 sure that all the items on this list level use the same bullet.
987 Furthermore, if this is an ordered list, make sure the numbering
991 Cycle the entire list level through the different itemize/enumerate
992 bullets (`-', `+', `*', `1.', `1)'). With prefix arg, select the
993 nth bullet from this list.
995 ---------- Footnotes ----------
997 (1) When using `*' as a bullet, lines must be indented or they will
998 be seen as top-level headlines. Also, when you are hiding leading
999 stars to get a clean outline view, plain list items starting with a
1000 star are visually indistinguishable from true headlines. In short:
1001 even though `*' is supported, it may be better not to use it for plain
1004 (2) Org-mode only changes the filling settings for Emacs. For
1005 XEmacs, you should use Kyle E. Jones' `filladapt.el'. To turn this on,
1006 put into `.emacs': `(require 'filladapt)'
1009 File: org, Node: Drawers, Next: orgstruct-mode, Prev: Plain lists, Up: Document structure
1014 Sometimes you want to keep information associated with an entry, but you
1015 normally don't want to see it. For this, Org-mode has _drawers_.
1016 Drawers need to be configured with the variable `org-drawers', and look
1019 ** This is a headline
1020 Still outside the drawer
1022 This is inside the drawer.
1026 Visibility cycling (*note Visibility cycling::) on the headline will
1027 hide and show the entry, but keep the drawer collapsed to a single line.
1028 In order to look inside the drawer, you need to move the cursor to the
1029 drawer line and press <TAB> there. Org-mode uses a drawer for storing
1030 properties (*note Properties and columns::).
1033 File: org, Node: orgstruct-mode, Prev: Drawers, Up: Document structure
1035 2.10 The Orgstruct minor mode
1036 =============================
1038 If you like the intuitive way the Org-mode structure editing and list
1039 formatting works, you might want to use these commands in other modes
1040 like text-mode or mail-mode as well. The minor mode Orgstruct-mode
1041 makes this possible. You can always toggle the mode with `M-x
1042 orgstruct-mode'. To turn it on by default, for example in mail mode,
1045 (add-hook 'mail-mode-hook 'turn-on-orgstruct)
1047 When this mode is active and the cursor is on a line that looks to
1048 Org-mode like a headline of the first line of a list item, most
1049 structure editing commands will work, even if the same keys normally
1050 have different functionality in the major mode you are using. If the
1051 cursor is not in one of those special lines, Orgstruct-mode lurks
1052 silently in the shadow.
1055 File: org, Node: Tables, Next: Hyperlinks, Prev: Document structure, Up: Top
1060 Org-mode has a very fast and intuitive table editor built-in.
1061 Spreadsheet-like calculations are supported in connection with the
1062 Emacs `calc' package.
1066 * Built-in table editor:: Simple tables
1067 * Narrow columns:: Stop wasting space in tables
1068 * Column groups:: Grouping to trigger vertical lines
1069 * orgtbl-mode:: The table editor as minor mode
1070 * The spreadsheet:: The table editor has spreadsheet capabilities.
1073 File: org, Node: Built-in table editor, Next: Narrow columns, Prev: Tables, Up: Tables
1075 3.1 The built-in table editor
1076 =============================
1078 Org-mode makes it easy to format tables in plain ASCII. Any line with
1079 `|' as the first non-white character is considered part of a table.
1080 `|' is also the column separator. A table might look like this:
1082 | Name | Phone | Age |
1083 |-------+-------+-----|
1084 | Peter | 1234 | 17 |
1085 | Anna | 4321 | 25 |
1087 A table is re-aligned automatically each time you press <TAB> or
1088 <RET> or `C-c C-c' inside the table. <TAB> also moves to the next
1089 field (<RET> to the next row) and creates new table rows at the end of
1090 the table or before horizontal lines. The indentation of the table is
1091 set by the first line. Any line starting with `|-' is considered as a
1092 horizontal separator line and will be expanded on the next re-align to
1093 span the whole table width. So, to create the above table, you would
1099 and then press <TAB> to align the table and start filling in fields.
1101 When typing text into a field, Org-mode treats <DEL>, <Backspace>,
1102 and all character keys in a special way, so that inserting and deleting
1103 avoids shifting other fields. Also, when typing _immediately after the
1104 cursor was moved into a new field with `<TAB>', `S-<TAB>' or `<RET>'_,
1105 the field is automatically made blank. If this behavior is too
1106 unpredictable for you, configure the variables
1107 `org-enable-table-editor' and `org-table-auto-blank-field'.
1109 Creation and conversion
1110 .......................
1113 Convert the active region to table. If every line contains at
1114 least one TAB character, the function assumes that the material is
1115 tab separated. If not, lines are split at whitespace into fields.
1116 You can use a prefix argument to indicate the minimum number of
1117 consecutive spaces required to identify a field separator
1118 (default: just one).
1119 If there is no active region, this command creates an empty
1120 Org-mode table. But it's easier just to start typing, like
1121 `|Name|Phone|Age <RET> |- <TAB>'.
1123 Re-aligning and field motion
1124 ............................
1127 Re-align the table without moving the cursor.
1130 Re-align the table, move to the next field. Creates a new row if
1134 Re-align, move to previous field.
1137 Re-align the table and move down to next row. Creates a new row if
1138 necessary. At the beginning or end of a line, <RET> still does
1139 NEWLINE, so it can be used to split a table.
1141 Column and row editing
1142 ......................
1146 Move the current column left/right.
1149 Kill the current column.
1152 Insert a new column to the left of the cursor position.
1156 Move the current row up/down.
1159 Kill the current row or horizontal line.
1162 Insert a new row above (with arg: below) the current row.
1165 Insert a horizontal line below current row. With prefix arg, the
1166 line is created above the current line.
1169 Sort the table lines in the region. The position of point
1170 indicates the column to be used for sorting, and the range of
1171 lines is the range between the nearest horizontal separator lines,
1172 or the entire table. If point is before the first column, you
1173 will be prompted for the sorting column. If there is an active
1174 region, the mark specifies the first line and the sorting column,
1175 while point should be in the last line to be included into the
1176 sorting. The command prompts for the sorting type
1177 (alphabetically, numerically, or by time). When called with a
1178 prefix argument, alphabetic sorting will be case-sensitive.
1184 Copy a rectangular region from a table to a special clipboard.
1185 Point and mark determine edge fields of the rectangle. The
1186 process ignores horizontal separator lines.
1189 Copy a rectangular region from a table to a special clipboard, and
1190 blank all fields in the rectangle. So this is the "cut" operation.
1193 Paste a rectangular region into a table. The upper right corner
1194 ends up in the current field. All involved fields will be
1195 overwritten. If the rectangle does not fit into the present table,
1196 the table is enlarged as needed. The process ignores horizontal
1200 Wrap several fields in a column like a paragraph. If there is an
1201 active region, and both point and mark are in the same column, the
1202 text in the column is wrapped to minimum width for the given
1203 number of lines. A prefix ARG may be used to change the number of
1204 desired lines. If there is no region, the current field is split
1205 at the cursor position and the text fragment to the right of the
1206 cursor is prepended to the field one line down. If there is no
1207 region, but you specify a prefix ARG, the current field is made
1208 blank, and the content is appended to the field above.
1214 Sum the numbers in the current column, or in the rectangle defined
1215 by the active region. The result is shown in the echo area and can
1216 be inserted with `C-y'.
1219 When current field is empty, copy from first non-empty field above.
1220 When not empty, copy current field down to next row and move cursor
1221 along with it. Depending on the variable
1222 `org-table-copy-increment', integer field values will be
1223 incremented during copy. This key is also used by CUA-mode (*note
1230 Edit the current field in a separate window. This is useful for
1231 fields that are not fully visible (*note Narrow columns::). When
1232 called with a `C-u' prefix, just make the full field visible, so
1233 that it can be edited in place.
1236 This is an alias for `C-u C-c `' to make the current field fully
1239 `M-x org-table-import'
1240 Import a file as a table. The table should be TAB- or whitespace
1241 separated. Useful, for example, to import an Excel table or data
1242 from a database, because these programs generally can write
1243 TAB-separated text files. This command works by inserting the
1244 file into the buffer and then converting the region to a table.
1245 Any prefix argument is passed on to the converter, which uses it
1246 to determine the separator.
1249 Tables can also be imported by pasting tabular text into the
1250 org-mode buffer, selecting the pasted text with `C-x C-x' and then
1251 using the `C-c |' command (see above under Creation and conversion.
1253 `M-x org-table-export'
1254 Export the table as a TAB-separated file. Useful for data
1255 exchange with, for example, Excel or database programs.
1257 If you don't like the automatic table editor because it gets in your
1258 way on lines which you would like to start with `|', you can turn it
1261 (setq org-enable-table-editor nil)
1263 Then the only table command that still works is `C-c C-c' to do a
1267 File: org, Node: Narrow columns, Next: Column groups, Prev: Built-in table editor, Up: Tables
1272 The width of columns is automatically determined by the table editor.
1273 Sometimes a single field or a few fields need to carry more text,
1274 leading to inconveniently wide columns. To limit(1) the width of a
1275 column, one field anywhere in the column may contain just the string
1276 `<N>' where `N' is an integer specifying the width of the column in
1277 characters. The next re-align will then set the width of this column
1278 to no more than this value.
1280 |---+------------------------------| |---+--------|
1282 | 1 | one | | 1 | one |
1283 | 2 | two | ----\ | 2 | two |
1284 | 3 | This is a long chunk of text | ----/ | 3 | This=> |
1285 | 4 | four | | 4 | four |
1286 |---+------------------------------| |---+--------|
1288 Fields that are wider become clipped and end in the string `=>'. Note
1289 that the full text is still in the buffer, it is only invisible. To
1290 see the full text, hold the mouse over the field - a tool-tip window
1291 will show the full content. To edit such a field, use the command `C-c
1292 `' (that is `C-c' followed by the backquote). This will open a new
1293 window with the full field. Edit it and finish with `C-c C-c'.
1295 When visiting a file containing a table with narrowed columns, the
1296 necessary character hiding has not yet happened, and the table needs to
1297 be aligned before it looks nice. Setting the option
1298 `org-startup-align-all-tables' will realign all tables in a file upon
1299 visiting, but also slow down startup. You can also set this option on
1300 a per-file basis with:
1305 ---------- Footnotes ----------
1307 (1) This feature does not work on XEmacs.
1310 File: org, Node: Column groups, Next: orgtbl-mode, Prev: Narrow columns, Up: Tables
1315 When Org-mode exports tables, it does so by default without vertical
1316 lines because that is visually more satisfying in general. Occasionally
1317 however, vertical lines can be useful to structure a table into groups
1318 of columns, much like horizontal lines can do for groups of rows. In
1319 order to specify column groups, you can use a special row where the
1320 first field contains only `/'. The further fields can either contain
1321 `<' to indicate that this column should start a group, `>' to indicate
1322 the end of a column, or `<>' to make a column a group of its own.
1323 Boundaries between colum groups will upon export be marked with
1324 vertical lines. Here is an example:
1326 | | N | N^2 | N^3 | N^4 | sqrt(n) | sqrt[4](N) |
1327 |---+----+-----+-----+-----+---------+------------|
1328 | / | <> | < | | > | < | > |
1329 | # | 1 | 1 | 1 | 1 | 1 | 1 |
1330 | # | 2 | 4 | 8 | 16 | 1.4142 | 1.1892 |
1331 | # | 3 | 9 | 27 | 81 | 1.7321 | 1.3161 |
1332 |---+----+-----+-----+-----+---------+------------|
1333 #+TBLFM: $3=$2^2::$4=$2^3::$5=$2^4::$6=sqrt($2)::$7=sqrt(sqrt(($2))
1335 It is also sufficient to just insert the colum group starters after
1336 every vertical line you'd like to have:
1338 | N | N^2 | N^3 | N^4 | sqrt(n) | sqrt[4](N) |
1339 |----+-----+-----+-----+---------+------------|
1343 File: org, Node: orgtbl-mode, Next: The spreadsheet, Prev: Column groups, Up: Tables
1345 3.4 The Orgtbl minor mode
1346 =========================
1348 If you like the intuitive way the Org-mode table editor works, you
1349 might also want to use it in other modes like text-mode or mail-mode.
1350 The minor mode Orgtbl-mode makes this possible. You can always toggle
1351 the mode with `M-x orgtbl-mode'. To turn it on by default, for example
1354 (add-hook 'mail-mode-hook 'turn-on-orgtbl)
1356 Furthermore, with some special setup, it is possible to maintain
1357 tables in arbitrary syntax with Orgtbl-mode. For example, it is
1358 possible to construct LaTeX tables with the underlying ease and power of
1359 Orgtbl-mode, including spreadsheet capabilities. For details, see
1360 *Note Tables in arbitrary syntax::.
1363 File: org, Node: The spreadsheet, Prev: orgtbl-mode, Up: Tables
1368 The table editor makes use of the Emacs `calc' package to implement
1369 spreadsheet-like capabilities. It can also evaluate Emacs Lisp forms to
1370 derive fields from other fields. While fully featured, Org-mode's
1371 implementation is not identical to other spreadsheets. For example,
1372 Org-mode knows the concept of a _column formula_ that will be applied
1373 to all non-header fields in a column without having to copy the formula
1374 to each relevant field.
1378 * References:: How to refer to another field or range
1379 * Formula syntax for Calc:: Using Calc to compute stuff
1380 * Formula syntax for Lisp:: Writing formulas in Emacs Lisp
1381 * Field formulas:: Formulas valid for a single field
1382 * Column formulas:: Formulas valid for an entire column
1383 * Editing and debugging formulas:: Fixing formulas
1384 * Updating the table:: Recomputing all dependent fields
1385 * Advanced features:: Field names, parameters and automatic recalc
1388 File: org, Node: References, Next: Formula syntax for Calc, Prev: The spreadsheet, Up: The spreadsheet
1393 To compute fields in the table from other fields, formulas must
1394 reference other fields or ranges. In Org-mode, fields can be referenced
1395 by name, by absolute coordinates, and by relative coordinates. To find
1396 out what the coordinates of a field are, press `C-c ?' in that field,
1397 or press `C-c }' to toggle the display of a grid.
1402 Formulas can reference the value of another field in two ways. Like in
1403 any other spreadsheet, you may reference fields with a letter/number
1404 combination like `B3', meaning the 2nd field in the 3rd row.
1406 Org-mode also uses another, more general operator that looks like this:
1409 Column references can be absolute like `1', `2',...`N', or relative to
1410 the current column like `+1' or `-2'.
1412 The row specification only counts data lines and ignores horizontal
1413 separator lines (hlines). You can use absolute row numbers `1'...`N',
1414 and row numbers relative to the current row like `+3' or `-1'. Or
1415 specify the row relative to one of the hlines: `I' refers to the first
1416 hline, `II' to the second etc. `-I' refers to the first such line
1417 above the current line, `+I' to the first such line below the current
1418 line. You can also write `III+2' which is the second data line after
1419 the third hline in the table. Relative row numbers like `-3' will not
1420 cross hlines if the current line is too close to the hline. Instead,
1421 the value directly at the hline is used.
1423 `0' refers to the current row and column. Also, if you omit either
1424 the column or the row part of the reference, the current row/column is
1427 Org-mode's references with _unsigned_ numbers are fixed references
1428 in the sense that if you use the same reference in the formula for two
1429 different fields, the same field will be referenced each time.
1430 Org-mode's references with _signed_ numbers are floating references
1431 because the same reference operator can reference different fields
1432 depending on the field being calculated by the formula.
1434 Here are a few examples:
1436 @2$3 2nd row, 3rd column
1438 $5 column 5 in the current row
1440 @2 current column, row 2
1441 @-1$-3 the field one row up, three columns to the left
1442 @-I$2 field just under hline above current row, column 2
1447 You may reference a rectangular range of fields by specifying two field
1448 references connected by two dots `..'. If both fields are in the
1449 current row, you may simply use `$2..$7', but if at least one field is
1450 in a different row, you need to use the general `@row$column' format at
1451 least for the first field (i.e the reference must start with `@' in
1452 order to be interpreted correctly). Examples:
1454 $1..$3 First three fields in the current row.
1455 $P..$Q Range, using column names (see under Advanced)
1456 @2$1..@4$3 6 fields between these two fields.
1457 A2..C4 Same as above.
1458 @-1$-2..@-1 3 numbers from the column to the left, 2 up to current row
1460 Range references return a vector of values that can be fed into Calc
1461 vector functions. Empty fields in ranges are normally suppressed, so
1462 that the vector contains only the non-empty fields (but see the `E'
1463 mode switch below). If there are no non-empty fields, `[0]' is
1464 returned to avoid syntax errors in formulas.
1469 `$name' is interpreted as the name of a column, parameter or constant.
1470 Constants are defined globally through the variable
1471 `org-table-formula-constants', and locally (for the file) through a
1474 #+CONSTANTS: c=299792458. pi=3.14 eps=2.4e-6
1476 Also properties (*note Properties and columns::) can be used as
1477 constants in table formulas: For a property `:XYZ:' use the name
1478 `$PROP_XYZ', and the property will be searched in the current outline
1479 entry and in the hierarchy above it. If you have the `constants.el'
1480 package, it will also be used to resolve constants, including natural
1481 constants like `$h' for Planck's constant, and units like `$km' for
1482 kilometers(1). Column names and parameters can be specified in special
1483 table lines. These are described below, see *Note Advanced features::.
1484 All names must start with a letter, and further consist of letters and
1487 ---------- Footnotes ----------
1489 (1) `Constant.el' can supply the values of constants in two
1490 different unit systems, `SI' and `cgs'. Which one is used depends on
1491 the value of the variable `constants-unit-system'. You can use the
1492 `#+STARTUP' options `constSI' and `constcgs' to set this value for the
1496 File: org, Node: Formula syntax for Calc, Next: Formula syntax for Lisp, Prev: References, Up: The spreadsheet
1498 3.5.2 Formula syntax for Calc
1499 -----------------------------
1501 A formula can be any algebraic expression understood by the Emacs
1502 `Calc' package. Note that `calc' has the non-standard convention that
1503 `/' has lower precedence than `*', so that `a/b*c' is interpreted as
1504 `a/(b*c)'. Before evaluation by `calc-eval' (*note calc-eval:
1505 (calc)Calling Calc from Your Programs.), variable substitution takes
1506 place according to the rules described above. The range vectors can be
1507 directly fed into the calc vector functions like `vmean' and `vsum'.
1509 A formula can contain an optional mode string after a semicolon.
1510 This string consists of flags to influence Calc and other modes during
1511 execution. By default, Org-mode uses the standard calc modes (precision
1512 12, angular units degrees, fraction and symbolic modes off. The display
1513 format, however, has been changed to `(float 5)' to keep tables
1514 compact. The default settings can be configured using the variable
1515 `org-calc-default-modes'.
1517 p20 switch the internal precision to 20 digits
1518 n3 s3 e2 f4 normal, scientific, engineering, or fixed display format
1519 D R angle modes: degrees, radians
1520 F S fraction and symbolic modes
1521 N interpret all fields as numbers, use 0 for non-numbers
1522 T force text interpretation
1523 E keep empty fields in ranges
1525 In addition, you may provide a `printf' format specifier to reformat
1526 the final result. A few examples:
1528 $1+$2 Sum of first and second field
1529 $1+$2;%.2f Same, format result to two decimals
1530 exp($2)+exp($1) Math functions can be used
1531 $0;%.1f Reformat current cell to 1 decimal
1532 ($3-32)*5/9 Degrees F -> C conversion
1533 $c/$1/$cm Hz -> cm conversion, using `constants.el'
1534 tan($1);Dp3s1 Compute in degrees, precision 3, display SCI 1
1535 sin($1);Dp3%.1e Same, but use printf specifier for display
1536 vmean($2..$7) Compute column range mean, using vector function
1537 vmean($2..$7);EN Same, but treat empty fields as 0
1538 taylor($3,x=7,2) taylor series of $3, at x=7, second degree
1540 Calc also contains a complete set of logical operations. For example
1542 if($1<20,teen,string("")) "teen" if age $1 less than 20, else empty
1545 File: org, Node: Formula syntax for Lisp, Next: Field formulas, Prev: Formula syntax for Calc, Up: The spreadsheet
1547 3.5.3 Emacs Lisp forms as formulas
1548 ----------------------------------
1550 It is also possible to write a formula in Emacs Lisp; this can be useful
1551 for string manipulation and control structures, if the Calc's
1552 functionality is not enough. If a formula starts with a single quote
1553 followed by an opening parenthesis, then it is evaluated as a lisp form.
1554 The evaluation should return either a string or a number. Just as with
1555 `calc' formulas, you can specify modes and a printf format after a
1556 semicolon. With Emacs Lisp forms, you need to be concious about the way
1557 field references are interpolated into the form. By default, a
1558 reference will be interpolated as a Lisp string (in double quotes)
1559 containing the field. If you provide the `N' mode switch, all
1560 referenced elements will be numbers (non-number fields will be zero) and
1561 interpolated as Lisp numbers, without quotes. If you provide the `L'
1562 flag, all fields will be interpolated literally, without quotes. I.e.,
1563 if you want a reference to be interpreted as a string by the Lisp form,
1564 enclode the reference operator itself in double quotes, like `"$3"'.
1565 Ranges are inserted as space-separated fields, so you can embed them in
1566 list or vector syntax. A few examples, note how the `N' mode is used
1567 when we do computations in lisp.
1569 Swap the first two characters of the content of column 1
1570 '(concat (substring $1 1 2) (substring $1 0 1) (substring $1 2))
1571 Add columns 1 and 2, equivalent to the Calc's `$1+$2'
1573 Compute the sum of columns 1-4, like Calc's `vsum($1..$4)'
1574 '(apply '+ '($1..$4));N
1577 File: org, Node: Field formulas, Next: Column formulas, Prev: Formula syntax for Lisp, Up: The spreadsheet
1579 3.5.4 Field formulas
1580 --------------------
1582 To assign a formula to a particular field, type it directly into the
1583 field, preceded by `:=', for example `:=$1+$2'. When you press <TAB>
1584 or <RET> or `C-c C-c' with the cursor still in the field, the formula
1585 will be stored as the formula for this field, evaluated, and the
1586 current field replaced with the result.
1588 Formulas are stored in a special line starting with `#+TBLFM:'
1589 directly below the table. If you typed the equation in the 4th field of
1590 the 3rd data line in the table, the formula will look like
1591 `@3$4=$1+$2'. When inserting/deleting/swapping column and rows with
1592 the appropriate commands, absolute references (but not relative ones)
1593 in stored formulas are modified in order to still reference the same
1594 field. Of cause this is not true if you edit the table structure with
1595 normal editing commands - then you must fix the equations yourself.
1597 Instead of typing an equation into the field, you may also use the
1601 Install a new formula for the current field. The command prompts
1602 for a formula, with default taken from the `#+TBLFM:' line, applies
1603 it to the current field and stores it.
1606 File: org, Node: Column formulas, Next: Editing and debugging formulas, Prev: Field formulas, Up: The spreadsheet
1608 3.5.5 Column formulas
1609 ---------------------
1611 Often in a table, the same formula should be used for all fields in a
1612 particular column. Instead of having to copy the formula to all fields
1613 in that column, org-mode allows to assign a single formula to an entire
1614 column. If the table contains horizontal separator hlines, everything
1615 before the first such line is considered part of the table _header_ and
1616 will not be modified by column formulas.
1618 To assign a formula to a column, type it directly into any field in
1619 the column, preceded by an equal sign, like `=$1+$2'. When you press
1620 <TAB> or <RET> or `C-c C-c' with the cursor still in the field, the
1621 formula will be stored as the formula for the current column, evaluated
1622 and the current field replaced with the result. If the field contains
1623 only `=', the previously stored formula for this column is used. For
1624 each column, Org-mode will only remember the most recently used
1625 formula. In the `TBLFM:' line, column formulas will look like
1628 Instead of typing an equation into the field, you may also use the
1632 Install a new formula for the current column and replace current
1633 field with the result of the formula. The command prompts for a
1634 formula, with default taken from the `#+TBLFM' line, applies it to
1635 the current field and stores it. With a numerical prefix (e.g.
1636 `C-5 C-c =') will apply it to that many consecutive fields in the
1640 File: org, Node: Editing and debugging formulas, Next: Updating the table, Prev: Column formulas, Up: The spreadsheet
1642 3.5.6 Editing and Debugging formulas
1643 ------------------------------------
1645 You can edit individual formulas in the minibuffer or directly in the
1646 field. Org-mode can also prepare a special buffer with all active
1647 formulas of a table. When offering a formula for editing, Org-mode
1648 converts references to the standard format (like `B3' or `D&') if
1649 possible. If you prefer to only work with the internal format (like
1650 `@3$2' or `$4'), configure the variable
1651 `org-table-use-standard-references'.
1655 Edit the formula associated with the current column/field in the
1656 minibuffer. See *Note Column formulas:: and *Note Field
1660 Re-insert the active formula (either a field formula, or a column
1661 formula) into the current field, so that you can edit it directly
1662 in the field. The advantage over editing in the minibuffer is
1663 that you can use the command `C-c ?'.
1666 While editing a formula in a table field, highlight the field(s)
1667 referenced by the reference at the cursor position in the formula.
1670 Toggle the display of row and column numbers for a table, using
1671 overlays. These are updated each time the table is aligned, you
1672 can force it with `C-c C-c'.
1675 Toggle the formula debugger on and off. See below.
1678 Edit all formulas for the current table in a special buffer, where
1679 the formulas will be displayed one per line. If the current field
1680 has an active formula, the cursor in the formula editor will mark
1681 it. While inside the special buffer, Org-mode will automatically
1682 highlight any field or range reference at the cursor position.
1683 You may edit, remove and add formulas, and use the following
1687 Exit the formula editor and store the modified formulas.
1688 With `C-u' prefix, also apply the new formulas to the entire
1692 Exit the formula editor without installing changes.
1695 Toggle all references in the formula editor between standard
1696 (like `B3') and internal (like `@3$2').
1699 Pretty-print or indent lisp formula at point. When in a line
1700 containing a lisp formula, format the formula according to
1701 Emacs Lisp rules. Another <TAB> collapses the formula back
1702 again. In the open formula, <TAB> re-indents just like in
1706 Complete Lisp symbols, just like in Emacs-lisp-mode.
1708 `S-<up>/<down>/<left>/<right>'
1709 Shift the reference at point. For example, if the reference
1710 is `B3' and you press `S-<right>', it will become `C3'. This
1711 also works for relative references, and for hline references.
1714 Move the test line for column formulas in the Org-mode buffer
1718 Scroll the window displaying the table.
1721 Turn the coordinate grid in the table on and off.
1723 Making a table field blank does not remove the formula associated
1724 with the field, because that is stored in a different line (the `TBLFM'
1725 line) - during the next recalculation the field will be filled again.
1726 To remove a formula from a field, you have to give an empty reply when
1727 prompted for the formula, or to edit the `#+TBLFM' line.
1729 You may edit the `#+TBLFM' directly and re-apply the changed
1730 equations with `C-c C-c' in that line, or with the normal recalculation
1731 commands in the table.
1736 When the evaluation of a formula leads to an error, the field content
1737 becomes the string `#ERROR'. If you would like see what is going on
1738 during variable substitution and calculation in order to find a bug,
1739 turn on formula debugging in the `Tbl' menu and repeat the calculation,
1740 for example by pressing `C-u C-u C-c = <RET>' in a field. Detailed
1741 information will be displayed.
1744 File: org, Node: Updating the table, Next: Advanced features, Prev: Editing and debugging formulas, Up: The spreadsheet
1746 3.5.7 Updating the Table
1747 ------------------------
1749 Recalculation of a table is normally not automatic, but needs to be
1750 triggered by a command. See *Note Advanced features:: for a way to make
1751 recalculation at least semi-automatically.
1753 In order to recalculate a line of a table or the entire table, use
1754 the following commands:
1757 Recalculate the current row by first applying the stored column
1758 formulas from left to right, and all field formulas in the current
1763 Recompute the entire table, line by line. Any lines before the
1764 first hline are left alone, assuming that these are part of the
1768 Iterate the table by recomputing it until no further changes occur.
1769 This may be necessary if some computed fields use the value of
1770 other fields that are computed later in the calculation sequence.
1773 File: org, Node: Advanced features, Prev: Updating the table, Up: The spreadsheet
1775 3.5.8 Advanced features
1776 -----------------------
1778 If you want the recalculation of fields to happen automatically, or if
1779 you want to be able to assign names to fields and columns, you need to
1780 reserve the first column of the table for special marking characters.
1782 Rotate the calculation mark in first column through the states `',
1783 `#', `*', `!', `$'. The meaning of these characters is discussed
1784 below. When there is an active region, change all marks in the
1787 Here is an example of a table that collects exam results of students
1788 and makes use of these features:
1790 |---+---------+--------+--------+--------+-------+------|
1791 | | Student | Prob 1 | Prob 2 | Prob 3 | Total | Note |
1792 |---+---------+--------+--------+--------+-------+------|
1793 | ! | | P1 | P2 | P3 | Tot | |
1794 | # | Maximum | 10 | 15 | 25 | 50 | 10.0 |
1795 | ^ | | m1 | m2 | m3 | mt | |
1796 |---+---------+--------+--------+--------+-------+------|
1797 | # | Peter | 10 | 8 | 23 | 41 | 8.2 |
1798 | # | Sara | 6 | 14 | 19 | 39 | 7.8 |
1799 | # | Sam | 2 | 4 | 3 | 9 | 1.8 |
1800 |---+---------+--------+--------+--------+-------+------|
1801 | | Average | | | | 29.7 | |
1802 | ^ | | | | | at | |
1803 | $ | max=50 | | | | | |
1804 |---+---------+--------+--------+--------+-------+------|
1805 #+TBLFM: $6=vsum($P1..$P3)::$7=10*$Tot/$max;%.1f::$at=vmean(@-II..@-I);%.1f
1807 Important: Please note that for these special tables, recalculating the
1808 table with `C-u C-c *' will only affect rows that are marked `#' or
1809 `*', and fields that have a formula assigned to the field itself. The
1810 column formulas are not applied in rows with empty first field.
1812 The marking characters have the following meaning:
1814 The fields in this line define names for the columns, so that you
1815 may refer to a column as `$Tot' instead of `$6'.
1818 This row defines names for the fields _above_ the row. With such
1819 a definition, any formula in the table may use `$m1' to refer to
1820 the value `10'. Also, if you assign a formula to a names field, it
1821 will be stored as `$name=...'.
1824 Similar to `^', but defines names for the fields in the row
1828 Fields in this row can define _parameters_ for formulas. For
1829 example, if a field in a `$' row contains `max=50', then formulas
1830 in this table can refer to the value 50 using `$max'. Parameters
1831 work exactly like constants, only that they can be defined on a
1835 Fields in this row are automatically recalculated when pressing
1836 <TAB> or <RET> or `S-<TAB>' in this row. Also, this row is
1837 selected for a global recalculation with `C-u C-c *'. Unmarked
1838 lines will be left alone by this command.
1841 Selects this line for global recalculation with `C-u C-c *', but
1842 not for automatic recalculation. Use this when automatic
1843 recalculation slows down editing too much.
1846 Unmarked lines are exempt from recalculation with `C-u C-c *'.
1847 All lines that should be recalculated should be marked with `#' or
1851 Do not export this line. Useful for lines that contain the
1852 narrowing `<N>' markers.
1854 Finally, just to whet your appetite on what can be done with the
1855 fantastic `calc' package, here is a table that computes the Taylor
1856 series of degree `n' at location `x' for a couple of functions
1857 (homework: try that with Excel :-)
1859 |---+-------------+---+-----+--------------------------------------|
1860 | | Func | n | x | Result |
1861 |---+-------------+---+-----+--------------------------------------|
1862 | # | exp(x) | 1 | x | 1 + x |
1863 | # | exp(x) | 2 | x | 1 + x + x^2 / 2 |
1864 | # | exp(x) | 3 | x | 1 + x + x^2 / 2 + x^3 / 6 |
1865 | # | x^2+sqrt(x) | 2 | x=0 | x*(0.5 / 0) + x^2 (2 - 0.25 / 0) / 2 |
1866 | # | x^2+sqrt(x) | 2 | x=1 | 2 + 2.5 x - 2.5 + 0.875 (x - 1)^2 |
1867 | * | tan(x) | 3 | x | 0.0175 x + 1.77e-6 x^3 |
1868 |---+-------------+---+-----+--------------------------------------|
1869 #+TBLFM: $5=taylor($2,$4,$3);n3
1872 File: org, Node: Hyperlinks, Next: TODO items, Prev: Tables, Up: Top
1877 Just like HTML, Org-mode provides links inside a file, and external
1878 links to other files, Usenet articles, emails, and much more.
1882 * Link format:: How links in Org-mode are formatted
1883 * Internal links:: Links to other places in the current file
1884 * External links:: URL-like links to the world
1885 * Handling links:: Creating, inserting and following
1886 * Link abbreviations:: Shortcuts for writing complex links
1887 * Search options:: Linking to a specific location
1888 * Custom searches:: When the default search is not enough
1889 * Remember:: Org-trees store quick notes
1892 File: org, Node: Link format, Next: Internal links, Prev: Hyperlinks, Up: Hyperlinks
1897 Org-mode will recognize plain URL-like links and activate them as
1898 clickable links. The general link format, however, looks like this:
1900 [[link][description]] or alternatively [[link]]
1902 Once a link in the buffer is complete (all brackets present),
1903 Org-mode will change the display so that `description' is displayed
1904 instead of `[[link][description]]' and `link' is displayed instead of
1905 `[[link]]'. Links will be highlighted in the face `org-link', which by
1906 default is an underlined face. You can directly edit the visible part
1907 of a link. Note that this can be either the `link' part (if there is
1908 no description) or the `description' part. To edit also the invisible
1909 `link' part, use `C-c C-l' with the cursor on the link.
1911 If you place the cursor at the beginning or just behind the end of
1912 the displayed text and press <BACKSPACE>, you will remove the
1913 (invisible) bracket at that location. This makes the link incomplete
1914 and the internals are again displayed as plain text. Inserting the
1915 missing bracket hides the link internals again. To show the internal
1916 structure of all links, use the menu entry `Org->Hyperlinks->Literal
1920 File: org, Node: Internal links, Next: External links, Prev: Link format, Up: Hyperlinks
1925 If the link does not look like a URL, it is considered to be internal in
1926 the current file. Links such as `[[My Target]]' or `[[My Target][Find
1927 my target]]' lead to a text search in the current file. The link can
1928 be followed with `C-c C-o' when the cursor is on the link, or with a
1929 mouse click (*note Handling links::). The preferred match for such a
1930 link is a dedicated target: the same string in double angular brackets.
1931 Targets may be located anywhere; sometimes it is convenient to put
1932 them into a comment line. For example
1936 In HTML export (*note HTML export::), such targets will become named
1937 anchors for direct access through `http' links(1).
1939 If no dedicated target exists, Org-mode will search for the words in
1940 the link. In the above example the search would be for `my target'.
1941 Links starting with a star like `*My Target' restrict the search to
1942 headlines. When searching, Org-mode will first try an exact match, but
1943 then move on to more and more lenient searches. For example, the link
1944 `[[*My Targets]]' will find any of the following:
1947 ** TODO my targets are bright
1948 ** my 20 targets are
1950 To insert a link targeting a headline, in-buffer completion can be
1951 used. Just type a star followed by a few optional letters into the
1952 buffer and press `M-<TAB>'. All headlines in the current buffer will be
1953 offered as completions. *Note Handling links::, for more commands
1956 Following a link pushes a mark onto Org-mode's own mark ring. You
1957 can return to the previous position with `C-c &'. Using this command
1958 several times in direct succession goes back to positions recorded
1963 * Radio targets:: Make targets trigger links in plain text.
1965 ---------- Footnotes ----------
1967 (1) Note that text before the first headline is usually not
1968 exported, so the first such target should be after the first headline.
1971 File: org, Node: Radio targets, Prev: Internal links, Up: Internal links
1976 You can configure Org-mode to link any occurrences of certain target
1977 names in normal text. So without explicitly creating a link, the text
1978 connects to the target radioing its position. Radio targets are
1979 enclosed by triple angular brackets. For example, a target `<<<My
1980 Target>>>' causes each occurrence of `my target' in normal text to
1981 become activated as a link. The Org-mode file is scanned automatically
1982 for radio targets only when the file is first loaded into Emacs. To
1983 update the target list during editing, press `C-c C-c' with the cursor
1987 File: org, Node: External links, Next: Handling links, Prev: Internal links, Up: Hyperlinks
1992 Org-mode supports links to files, websites, Usenet and email messages,
1993 and BBDB database entries. External links are URL-like locators. They
1994 start with a short identifying string followed by a colon. There can be
1995 no space after the colon. The following list shows examples for each
1998 http://www.astro.uva.nl/~dominik on the web
1999 file:/home/dominik/images/jupiter.jpg file, absolute path
2000 file:papers/last.pdf file, relative path
2001 news:comp.emacs Usenet link
2002 mailto:adent@galaxy.net Mail link
2003 vm:folder VM folder link
2004 vm:folder#id VM message link
2005 vm://myself@some.where.org/folder#id VM on remote machine
2006 wl:folder WANDERLUST folder link
2007 wl:folder#id WANDERLUST message link
2008 mhe:folder MH-E folder link
2009 mhe:folder#id MH-E message link
2010 rmail:folder RMAIL folder link
2011 rmail:folder#id RMAIL message link
2012 gnus:group GNUS group link
2013 gnus:group#id GNUS article link
2014 bbdb:Richard Stallman BBDB link
2015 shell:ls *.org A shell command
2016 elisp:(find-file-other-frame "Elisp.org") An elisp form to evaluate
2018 A link should be enclosed in double brackets and may contain a
2019 descriptive text to be displayed instead of the url (*note Link
2020 format::), for example:
2022 [[http://www.gnu.org/software/emacs/][GNU Emacs]]
2024 If the description is a file name or URL that points to an image, HTML
2025 export (*note HTML export::) will inline the image as a clickable
2026 button. If there is no description at all and the link points to an
2027 image, that image will be inlined into the exported HTML file.
2029 Org-mode also finds external links in the normal text and activates
2030 them as links. If spaces must be part of the link (for example in
2031 `bbdb:Richard Stallman'), or if you need to remove ambiguities about
2032 the end of the link, enclose them in angular brackets.
2035 File: org, Node: Handling links, Next: Link abbreviations, Prev: External links, Up: Hyperlinks
2040 Org-mode provides methods to create a link in the correct syntax, to
2041 insert it into an org-mode file, and to follow the link.
2044 Store a link to the current location. This is a _global_ command
2045 which can be used in any buffer to create a link. The link will be
2046 stored for later insertion into an Org-mode buffer (see below).
2047 For Org-mode files, if there is a `<<target>>' at the cursor, the
2048 link points to the target. Otherwise it points to the current
2049 headline. For VM, RMAIL, WANDERLUST, MH-E, GNUS and BBDB buffers,
2050 the link will indicate the current article/entry. For W3 and W3M
2051 buffers, the link goes to the current URL. For any other files,
2052 the link will point to the file, with a search string (*note
2053 Search options::) pointing to the contents of the current line.
2054 If there is an active region, the selected words will form the
2055 basis of the search string. If the automatically created link is
2056 not working correctly or accurately enough, you can write custom
2057 functions to select the search string and to do the search for
2058 particular file types - see *Note Custom searches::. The key
2059 binding `C-c l' is only a suggestion - see *Note Installation::.
2062 Insert a link. This prompts for a link to be inserted into the
2063 buffer. You can just type a link, using text for an internal
2064 link, or one of the link type prefixes mentioned in the examples
2065 above. All links stored during the current session are part of
2066 the history for this prompt, so you can access them with <up> and
2067 <down>. Completion, on the other hand, will help you to insert
2068 valid link prefixes like `http:' or `ftp:', including the prefixes
2069 defined through link abbreviations (*note Link abbreviations::).
2070 The link will be inserted into the buffer(1), along with a
2071 descriptive text. If some text was selected when this command is
2072 called, the selected text becomes the default description.
2073 Note that you don't have to use this command to insert a link.
2074 Links in Org-mode are plain text, and you can type or paste them
2075 straight into the buffer. By using this command, the links are
2076 automatically enclosed in double brackets, and you will be asked
2077 for the optional descriptive text.
2080 When `C-c C-l' is called with a `C-u' prefix argument, a link to a
2081 file will be inserted and you may use file name completion to
2082 select the name of the file. The path to the file is inserted
2083 relative to the directory of the current org file, if the linked
2084 file is in the current directory or in a subdirectory of it, or if
2085 the path is written relative to the current directory using `../'.
2086 Otherwise an absolute path is used, if possible with `~/' for
2087 your home directory. You can force an absolute path with two
2090 `C-c C-l (with cursor on existing link)'
2091 When the cursor is on an existing link, `C-c C-l' allows you to
2092 edit the link and description parts of the link.
2095 Open link at point. This will launch a web browser for URLs (using
2096 `browse-url-at-point'), run vm/mh-e/wanderlust/rmail/gnus/bbdb for
2097 the corresponding links, and execute the command in a shell link.
2098 When the cursor is on an internal link, this commands runs the
2099 corresponding search. When the cursor is on a TAG list in a
2100 headline, it creates the corresponding TAGS view. If the cursor
2101 is on a time stamp, it compiles the agenda for that date.
2102 Furthermore, it will visit text and remote files in `file:' links
2103 with Emacs and select a suitable application for local non-text
2104 files. Classification of files is based on file extension only.
2105 See option `org-file-apps'. If you want to override the default
2106 application and visit the file with Emacs, use a `C-u' prefix.
2110 On links, `mouse-2' will open the link just as `C-c C-o' would.
2111 Under Emacs 22, also `mouse-1' will follow a link.
2114 Like `mouse-2', but force file links to be opened with Emacs, and
2115 internal links to be displayed in another window(2).
2118 Push the current position onto the mark ring, to be able to return
2119 easily. Commands following an internal link do this automatically.
2122 Jump back to a recorded position. A position is recorded by the
2123 commands following internal links, and by `C-c %'. Using this
2124 command several times in direct succession moves through a ring of
2125 previously recorded positions.
2129 Move forward/backward to the next link in the buffer. At the
2130 limit of the buffer, the search fails once, and then wraps around.
2131 The key bindings for this are really too long, you might want to
2132 bind this also to `C-n' and `C-p'
2133 (add-hook 'org-load-hook
2135 (define-key 'org-mode-map "\C-n" 'org-next-link)
2136 (define-key 'org-mode-map "\C-p" 'org-previous-link)))
2138 ---------- Footnotes ----------
2140 (1) After insertion of a stored link, the link will be removed from
2141 the list of stored links. To keep it in the list later use, use a
2142 triple `C-u' prefix to `C-c C-l', or configure the option
2143 `org-keep-stored-link-after-insertion'.
2145 (2) See the variable `org-display-internal-link-with-indirect-buffer'
2148 File: org, Node: Link abbreviations, Next: Search options, Prev: Handling links, Up: Hyperlinks
2150 4.5 Link abbreviations
2151 ======================
2153 Long URLs can be cumbersome to type, and often many similar links are
2154 needed in a document. For this you can use link abbreviations. An
2155 abbreviated link looks like this
2157 [[linkword:tag][description]]
2159 where the tag is optional. Such abbreviations are resolved according to
2160 the information in the variable `org-link-abbrev-alist' that relates
2161 the linkwords to replacement text. Here is an example:
2163 (setq org-link-abbrev-alist
2164 '(("bugzilla" . "http://10.1.2.9/bugzilla/show_bug.cgi?id=")
2165 ("google" . "http://www.google.com/search?q=")
2166 ("ads" . "http://adsabs.harvard.edu/cgi-bin/
2167 nph-abs_connect?author=%s&db_key=AST")))
2169 If the replacement text contains the string `%s', it will be
2170 replaced with the tag. Otherwise the tag will be appended to the string
2171 in order to create the link. You may also specify a function that will
2172 be called with the tag as the only argument to create the link.
2174 With the above setting, you could link to a specific bug with
2175 `[[bugzilla:129]]', search the web for `OrgMode' with
2176 `[[google:OrgMode]]' and find out what the Org-mode author is doing
2177 besides Emacs hacking with `[[ads:Dominik,C]]'.
2179 If you need special abbreviations just for a single Org-mode buffer,
2180 you can define them in the file with
2182 #+LINK: bugzilla http://10.1.2.9/bugzilla/show_bug.cgi?id=
2183 #+LINK: google http://www.google.com/search?q=%s
2185 In-buffer completion *note Completion:: can be used after `[' to
2186 complete link abbreviations.
2189 File: org, Node: Search options, Next: Custom searches, Prev: Link abbreviations, Up: Hyperlinks
2191 4.6 Search options in file links
2192 ================================
2194 File links can contain additional information to make Emacs jump to a
2195 particular location in the file when following a link. This can be a
2196 line number or a search option after a double(1) colon. For example,
2197 when the command `C-c l' creates a link (*note Handling links::) to a
2198 file, it encodes the words in the current line as a search string that
2199 can be used to find this line back later when following the link with
2202 Here is the syntax of the different ways to attach a search to a file
2203 link, together with an explanation:
2205 [[file:~/code/main.c::255]]
2206 [[file:~/xx.org::My Target]]
2207 [[file:~/xx.org::*My Target]]
2208 [[file:~/xx.org::/regexp/]]
2214 Search for a link target `<<My Target>>', or do a text search for
2215 `my target', similar to the search in internal links, see *Note
2216 Internal links::. In HTML export (*note HTML export::), such a
2217 file link will become an HTML reference to the corresponding named
2218 anchor in the linked file.
2221 In an Org-mode file, restrict search to headlines.
2224 Do a regular expression search for `regexp'. This uses the Emacs
2225 command `occur' to list all matches in a separate window. If the
2226 target file is in Org-mode, `org-occur' is used to create a sparse
2227 tree with the matches.
2229 As a degenerate case, a file link with an empty file name can be used
2230 to search the current file. For example, `[[file:::find me]]' does a
2231 search for `find me' in the current file, just as `[[find me]]' would.
2233 ---------- Footnotes ----------
2235 (1) For backward compatibility, line numbers can also follow a
2239 File: org, Node: Custom searches, Next: Remember, Prev: Search options, Up: Hyperlinks
2244 The default mechanism for creating search strings and for doing the
2245 actual search related to a file link may not work correctly in all
2246 cases. For example, BibTeX database files have many entries like
2247 `year="1993"' which would not result in good search strings, because
2248 the only unique identification for a BibTeX entry is the citation key.
2250 If you come across such a problem, you can write custom functions to
2251 set the right search string for a particular file type, and to do the
2252 search for the string in the file. Using `add-hook', these functions
2253 need to be added to the hook variables
2254 `org-create-file-search-functions' and
2255 `org-execute-file-search-functions'. See the docstring for these
2256 variables for more information. Org-mode actually uses this mechanism
2257 for BibTeX database files, and you can use the corresponding code as an
2258 implementation example. Search for `BibTeX links' in the source file.
2261 File: org, Node: Remember, Prev: Custom searches, Up: Hyperlinks
2266 Another way to create org entries with links to other files is through
2267 the remember package by John Wiegley. Remember lets you store quick
2268 notes with little interruption of your work flow. See
2269 `http://www.emacswiki.org/cgi-bin/wiki/RememberMode' for more
2270 information. The notes produced by Remember can be stored in different
2271 ways, and Org-mode files are a good target. Org-mode significantly
2272 expands the possibilities of remember: You may define templates for
2273 different note types, and to associate target files and headlines with
2274 specific templates. It also allows you to select the location where a
2275 note should be stored interactively, on the fly.
2279 * Setting up remember:: Some code for .emacs to get things going
2280 * Remember templates:: Define the outline of different note types
2281 * Storing notes:: Directly get the note to where it belongs
2284 File: org, Node: Setting up remember, Next: Remember templates, Prev: Remember, Up: Remember
2286 4.8.1 Setting up remember
2287 -------------------------
2289 The following customization will tell remember to use org files as
2290 target, and to create annotations compatible with Org-mode links.
2292 (setq org-directory "~/path/to/my/orgfiles/")
2293 (setq org-default-notes-file "~/.notes")
2294 (setq remember-annotation-functions '(org-remember-annotation))
2295 (setq remember-handler-functions '(org-remember-handler))
2296 (add-hook 'remember-mode-hook 'org-remember-apply-template)
2299 File: org, Node: Remember templates, Next: Storing notes, Prev: Setting up remember, Up: Remember
2301 4.8.2 Remember templates
2302 ------------------------
2304 In combination with Org-mode, you can use templates to generate
2305 different types of remember notes. For example, if you would like to
2306 use one template to create general TODO entries, another one for
2307 journal entries, and a third one for collecting random ideas, you could
2310 (setq org-remember-templates
2311 '((?t "* TODO %?\n %i\n %a" "~/org/TODO.org")
2312 (?j "* %U %?\n\n %i\n %a" "~/org/JOURNAL.org")
2313 (?i "* %^{Title}\n %i\n %a" "~/org/JOURNAL.org" "New Ideas")))
2315 In these entries, the character specifies how to select the template.
2316 The first string specifies the template. Two more (optional) strings
2317 give the file in which, and the headline under which the new note
2318 should be stored. The file defaults (if not present or `nil') to
2319 `org-default-notes-file', the heading to
2320 `org-remember-default-headline'. Both defaults help to get to the
2321 storing location quickly, but you can change the location interactively
2322 while storing the note.
2324 When you call `M-x remember' (or `M-x org-remember') to remember
2325 something, org will prompt for a key to select the template (if you have
2326 more than one template) and then prepare the buffer like
2328 [[file:link to where you called remember]]
2332 * [2006-03-21 Tue 15:37]
2334 [[file:link to where you called remember]]
2336 During expansion of the template, special `%'-escapes allow dynamic
2337 insertion of content:
2338 %^{prompt} prompt the user for a string and replace this sequence with it.
2339 %t time stamp, date only
2340 %T time stamp with date and time
2341 %u, %U like the above, but inactive time stamps
2342 %^t like `%t', but prompt for date. Similarly `%^T', `%^u', `%^U'
2343 You may define a prompt like `%^{Birthday}t'
2344 %n user name (taken from `user-full-name')
2345 %a annotation, normally the link created with `org-store-link'
2346 %i initial content, the region when remember is called with C-u.
2347 The entire text will be indented like `%i' itself.
2348 %^g prompt for tags, with completion on tags in target file.
2349 %^G prompt for tags, with completion all tags in all agenda files.
2350 %:keyword specific information for certain link types, see below
2352 For specific link types, the following keywords will be defined:
2354 Link type | Available keywords
2355 -------------------+----------------------------------------------
2356 bbdb | %:name %:company
2357 vm, wl, mh, rmail | %:type %:subject %:message-id
2358 | %:from %:fromname %:fromaddress
2359 | %:to %:toname %:toaddress
2360 | %:fromto (either "to NAME" or "from NAME")(1)
2361 gnus | %:group, for messages also all email fields
2363 info | %:file %:node
2366 To place the cursor after template expansion use:
2368 %? After completing the template, position cursor here.
2370 If you change you mind about which template to use, call `org-remember'
2371 in the remember buffer. You may then select a new template that will
2372 be filled with the previous context information.
2374 ---------- Footnotes ----------
2376 (1) This will always be the other, not the user. See the variable
2377 `org-from-is-user-regexp'.
2380 File: org, Node: Storing notes, Prev: Remember templates, Up: Remember
2385 When you are finished preparing a note with remember, you have to press
2386 `C-c C-c' to file the note away. The handler first prompts for a
2387 target file - if you press <RET>, the value specified for the template
2388 is used. Then the command offers the headings tree of the selected
2389 file, with the cursor position at the default headline (if you had
2390 specified one in the template). You can either immediately press <RET>
2391 to get the note placed there. Or you can use the following keys to
2392 find a better location:
2393 <TAB> Cycle visibility.
2394 <down> / <up> Next/previous visible headline.
2395 n / p Next/previous visible headline.
2396 f / b Next/previous headline same level.
2398 Pressing <RET> or <left> or <right> then leads to the following
2401 Cursor Key Note gets inserted
2403 buffer-start <RET> as level 2 heading at end of file
2404 on headline <RET> as sublevel of the heading at cursor
2405 <left>/<right>as same level, before/after current heading
2406 not on <RET> at cursor position, level taken from context.
2409 So a fast way to store the note to its default location is to press
2410 `C-c C-c <RET> <RET>'. Even shorter would be `C-u C-c C-c', which does
2411 the same without even asking for a file or showing the tree.
2413 Before inserting the text into a tree, the function ensures that the
2414 text has a headline, i.e. a first line that starts with a `*'. If not,
2415 a headline is constructed from the current date and some additional
2416 data. If the variable `org-adapt-indentation' is non-nil, the entire
2417 text is also indented so that it starts in the same column as the
2418 headline (after the asterisks).
2421 File: org, Node: TODO items, Next: Tags, Prev: Hyperlinks, Up: Top
2426 Org-mode does not maintain TODO lists as a separate document. TODO
2427 items are an integral part of the notes file, because TODO items
2428 usually come up while taking notes! With Org-mode, you simply mark any
2429 entry in a tree as being a TODO item. In this way, the information is
2430 not duplicated, and the entire context from which the item emerged is
2431 always present when you check.
2433 Of course, this technique causes TODO items to be scattered
2434 throughout your file. Org-mode provides methods to give you an
2435 overview over all things you have to do.
2439 * TODO basics:: Marking and displaying TODO entries
2440 * TODO extensions:: Workflow and assignments
2441 * Priorities:: Some things are more important than others
2442 * Breaking down tasks:: Splitting a task into manageable pieces
2443 * Checkboxes:: Tick-off lists
2446 File: org, Node: TODO basics, Next: TODO extensions, Prev: TODO items, Up: TODO items
2448 5.1 Basic TODO functionality
2449 ============================
2451 Any headline can become a TODO item by starting it with the word TODO,
2454 *** TODO Write letter to Sam Fortune
2456 The most important commands to work with TODO entries are:
2459 Rotate the TODO state of the current item among
2461 ,-> (unmarked) -> TODO -> DONE --.
2462 '--------------------------------'
2464 The same rotation can also be done "remotely" from the timeline and
2465 agenda buffers with the `t' command key (*note Agenda commands::).
2469 Select the following/preceding TODO state, similar to cycling.
2470 Mostly useful if more than two TODO states are possible (*note
2474 View TODO items in a _sparse tree_ (*note Sparse trees::). Folds
2475 the entire buffer, but shows all TODO items and the headings
2476 hierarchy above them. With prefix arg, search for a specific
2477 TODO. You will be prompted for the keyword, and you can also give
2478 a list of keywords like `kwd1|kwd2|...'. With numerical prefix N,
2479 show the tree for the Nth keyword in the variable
2480 `org-todo-keywords'. With two prefix args, find all TODO and DONE
2484 Show the global TODO list. This collects the TODO items from all
2485 agenda files (*note Agenda views::) into a single buffer. The
2486 buffer is in `agenda-mode', so there are commands to examine and
2487 manipulate the TODO entries directly from that buffer (*note
2488 Agenda commands::). *Note Global TODO list::, for more
2492 Insert a new TODO entry below the current one.
2495 File: org, Node: TODO extensions, Next: Priorities, Prev: TODO basics, Up: TODO items
2497 5.2 Extended use of TODO keywords
2498 =================================
2500 The default implementation of TODO entries is just two states: TODO and
2501 DONE. You can use the TODO feature for more complicated things by
2502 configuring the variable `org-todo-keywords'. With special setup, the
2503 TODO keyword system can work differently in different files.
2505 Note that tags are another way to classify headlines in general and
2506 TODO items in particular (*note Tags::).
2510 * Workflow states:: From TODO to DONE in steps
2511 * TODO types:: I do this, Fred the rest
2512 * Multiple sets in one file:: Mixing it all, and still finding your way
2513 * Per file keywords:: Different files, different requirements
2516 File: org, Node: Workflow states, Next: TODO types, Prev: TODO extensions, Up: TODO extensions
2518 5.2.1 TODO keywords as workflow states
2519 --------------------------------------
2521 You can use TODO keywords to indicate different _sequential_ states in
2522 the process of working on an item, for example(1):
2524 (setq org-todo-keywords
2525 '((sequence "TODO" "FEEDBACK" "VERIFY" "|" "DONE" "DELEGATED")))
2527 The vertical bar separates the TODO keywords (states that _need
2528 action_) from the DONE states (which need _no further action_. If you
2529 don't provide the separator bar, the last state is used as the DONE
2530 state. With this setup, the command `C-c C-t' will cycle an entry from
2531 TODO to FEEDBACK, then to VERIFY, and finally to DONE and DELEGATED.
2532 You may also use a prefix argument to quickly select a specific state.
2533 For example `C-3 C-c C-t' will change the state immediately to VERIFY.
2534 If you define many keywords, you can use in-buffer completion (see
2535 *Note Completion::) to insert these words into the buffer. Changing a
2536 todo state can be logged with a timestamp, see *Note Tracking TODO
2537 state changes:: for more information.
2539 ---------- Footnotes ----------
2541 (1) Changing this variable only becomes effective after restarting
2542 Org-mode in a buffer.
2545 File: org, Node: TODO types, Next: Multiple sets in one file, Prev: Workflow states, Up: TODO extensions
2547 5.2.2 TODO keywords as types
2548 ----------------------------
2550 The second possibility is to use TODO keywords to indicate different
2551 _types_ of action items. For example, you might want to indicate that
2552 items are for "work" or "home". Or, when you work with several people
2553 on a single project, you might want to assign action items directly to
2554 persons, by using their names as TODO keywords. This would be set up
2557 (setq org-todo-keywords '((type "Fred" "Sara" "Lucy" "|" "DONE")))
2559 In this case, different keywords do not indicate a sequence, but
2560 rather different types. So the normal work flow would be to assign a
2561 task to a person, and later to mark it DONE. Org-mode supports this
2562 style by adapting the workings of the command `C-c C-t'(1). When used
2563 several times in succession, it will still cycle through all names, in
2564 order to first select the right type for a task. But when you return
2565 to the item after some time and execute `C-c C-t' again, it will switch
2566 from any name directly to DONE. Use prefix arguments or completion to
2567 quickly select a specific name. You can also review the items of a
2568 specific TODO type in a sparse tree by using a numeric prefix to `C-c
2569 C-v'. For example, to see all things Lucy has to do, you would use
2570 `C-3 C-c C-v'. To collect Lucy's items from all agenda files into a
2571 single buffer, you would use the prefix arg as well when creating the
2572 global todo list: `C-3 C-c t'.
2574 ---------- Footnotes ----------
2576 (1) This is also true for the `t' command in the timeline and agenda
2580 File: org, Node: Multiple sets in one file, Next: Per file keywords, Prev: TODO types, Up: TODO extensions
2582 5.2.3 Multiple keyword sets in one file
2583 ---------------------------------------
2585 Sometimes you may want to use different sets of TODO keywords in
2586 parallel. For example, you may want to have the basic `TODO'/`DONE',
2587 but also a workflow for bug fixing, and a separate state indicating
2588 that an item has been canceled (so it is not DONE, but also does not
2589 require action). Your setup would then look like this:
2591 (setq org-todo-keywords
2592 '((sequence "TODO" "|" "DONE")
2593 (sequence "REPORT" "BUG" "KNOWNCAUSE" "|" "FIXED")
2594 (sequence "|" "CANCELED")))
2596 The keywords should all be different, this helps Org-mode to keep
2597 track of which subsequence should be used for a given entry. In this
2598 setup, `C-c C-t' only operates within a subsequence, so it switches from
2599 `DONE' to (nothing) to `TODO', and from `FIXED' to (nothing) to
2600 `REPORT'. Therefore you need a mechanism to initially select the
2601 correct sequence. Besides the obvious ways like typing a keyword or
2602 using completion, you may also apply the following commands:
2606 These keys jump from one TODO subset to the next. In the above
2607 example, `C-S-<right>' would jump from `TODO' or `DONE' to
2608 `REPORT', and any of the words in the second row to `CANCELED'.
2612 `S-<<left>>' and `S-<<right>>' and walk through _all_ keywords
2613 from all sets, so for example `S-<<right>>' would switch from
2614 `DONE' to `REPORT' in the example above.
2617 File: org, Node: Per file keywords, Prev: Multiple sets in one file, Up: TODO extensions
2619 5.2.4 Setting up keywords for individual files
2620 ----------------------------------------------
2622 It can be very useful to use different aspects of the TODO mechanism in
2623 different files. For file-local settings, you need to add special lines
2624 to the file which set the keywords and interpretation for that file
2625 only. For example, to set one of the two examples discussed above, you
2626 need one of the following lines, starting in column zero anywhere in the
2629 #+SEQ_TODO: TODO FEEDBACK VERIFY | DONE CANCELED
2631 #+TYP_TODO: Fred Sara Lucy Mike | DONE
2633 A setup for using several sets in parallel would be:
2635 #+SEQ_TODO: "TODO" "|" "DONE"
2636 #+SEQ_TODO: "REPORT" "BUG" "KNOWNCAUSE" "|" "FIXED"
2637 #+SEQ_TODO: "|" "CANCELED"
2639 To make sure you are using the correct keyword, type `#+' into the
2640 buffer and then use `M-<TAB>' completion.
2642 Remember that the keywords after the vertical bar (or the last
2643 keyword if no bar is there) must always mean that the item is DONE
2644 (although you may use a different word). After changing one of these
2645 lines, use `C-c C-c' with the cursor still in the line to make the
2646 changes known to Org-mode(1).
2648 ---------- Footnotes ----------
2650 (1) Org-mode parses these lines only when Org-mode is activated
2651 after visiting a file. `C-c C-c' with the cursor in a line starting
2652 with `#+' is simply restarting Org-mode for the current buffer.
2655 File: org, Node: Priorities, Next: Breaking down tasks, Prev: TODO extensions, Up: TODO items
2660 If you use Org-mode extensively to organize your work, you may end up
2661 with a number of TODO entries so large that you'd like to prioritize
2662 them. This can be done by placing a _priority cookie_ into the
2665 *** TODO [#A] Write letter to Sam Fortune
2667 With its standard setup, Org-mode supports priorities `A', `B', and
2668 `C'. `A' is the highest priority. An entry without a cookie is
2669 treated as priority `B'. Priorities make a difference only in the
2670 agenda (*note Weekly/Daily agenda::).
2673 Set the priority of the current headline. The command prompts for
2674 a priority character `A', `B' or `C'. When you press <SPC>
2675 instead, the priority cookie is removed from the headline. The
2676 priorities can also be changed "remotely" from the timeline and
2677 agenda buffer with the `,' command (*note Agenda commands::).
2681 Increase/decrease priority of current headline. Note that these
2682 keys are also used to modify time stamps (*note Creating
2683 timestamps::). Furthermore, these keys are also used by CUA-mode
2684 (*note Conflicts::).
2686 You can change the range of allowed priorities by setting the
2687 variables `org-highest-priority', `org-lowest-priority', and
2688 `org-default-priority'. For an individual buffer, you may set these
2689 values (highest, lowest, default) like this (please make sure that the
2690 highest priority is earlier in the alphabet than the lowest priority):
2695 File: org, Node: Breaking down tasks, Next: Checkboxes, Prev: Priorities, Up: TODO items
2697 5.4 Breaking tasks down into subtasks
2698 =====================================
2700 It is often advisable to break down large tasks into smaller, manageable
2701 subtasks. You can do this by creating an outline tree below a TODO
2702 item, with detailed subtasks on the tree(1). Another possibility is
2703 the use of checkboxes to identify (a hierarchy of) a large number of
2704 subtasks (*note Checkboxes::).
2706 ---------- Footnotes ----------
2708 (1) To keep subtasks out of the global TODO list, see the
2709 `org-agenda-todo-list-sublevels'.
2712 File: org, Node: Checkboxes, Prev: Breaking down tasks, Up: TODO items
2717 Every item in a plain list (*note Plain lists::) can be made a checkbox
2718 by starting it with the string `[ ]'. This feature is similar to TODO
2719 items (*note TODO items::), but more lightweight. Checkboxes are not
2720 included into the global TODO list, so they are often great to split a
2721 task into a number of simple steps. Or you can use them in a shopping
2722 list. To toggle a checkbox, use `C-c C-c', or try Piotr Zielinski's
2723 `org-mouse.el'. Here is an example of a checkbox list.
2725 * TODO Organize party [3/6]
2731 - [ ] think about what music to play
2732 - [X] talk to the neighbors
2734 The `[3/6]' and `[1/3]' in the first and second line are cookies
2735 indicating how many checkboxes are present in this entry, and how many
2736 of them have been checked off. This can give you an idea on how many
2737 checkboxes remain, even without opening a folded entry. The cookies
2738 can be placed into a headline or into (the first line of) a plain list
2739 item. Each cookie covers all checkboxes structurally below that
2740 headline/item. You have to insert the cookie yourself by typing either
2741 `[/]' or `[%]'. In the first case you get an `n out of m' result, in
2742 the second case you get information about the percentage of checkboxes
2743 checked (in the above example, this would be `[50%]' and `[33%],
2746 The following commands work with checkboxes:
2749 Toggle checkbox at point.
2752 Toggle checkbox at point.
2753 - If there is an active region, toggle the first checkbox in
2754 the region and set all remaining boxes to the same status as
2755 the first. If you want to toggle all boxes in the region
2756 independently, use a prefix argument.
2758 - If the cursor is in a headline, toggle checkboxes in the
2759 region between this headline and the next (so _not_ the
2762 - If there is no active region, just toggle the checkbox at
2766 Insert a new item with a checkbox. This works only if the cursor
2767 is already in a plain list item (*note Plain lists::).
2770 Update the checkbox statistics in the current outline entry. When
2771 called with a `C-u' prefix, update the entire file. Checkbox
2772 statistic cookies are updated automatically if you toggle
2773 checkboxes with `C-c C-c' and make new ones with `M-S-<RET>'. If
2774 you delete boxes or add/change them by hand, use this command to
2775 get things back into synch. Or simply toggle any checkbox twice
2779 File: org, Node: Tags, Next: Properties and columns, Prev: TODO items, Up: Top
2784 If you wish to implement a system of labels and contexts for
2785 cross-correlating information, an excellent way is to assign tags to
2786 headlines. Org-mode has extensive support for using tags.
2788 Every headline can contain a list of tags, at the end of the
2789 headline. Tags are normal words containing letters, numbers, `_', and
2790 `@'. Tags must be preceded and followed by a single colon; like
2791 `:WORK:'. Several tags can be specified like `:WORK:URGENT:'.
2795 * Tag inheritance:: Tags use the tree structure of the outline
2796 * Setting tags:: How to assign tags to a headline
2797 * Tag searches:: Searching for combinations of tags
2800 File: org, Node: Tag inheritance, Next: Setting tags, Prev: Tags, Up: Tags
2805 Tags make use of the hierarchical structure of outline trees. If a
2806 heading has a certain tag, all subheadings will inherit the tag as
2807 well. For example, in the list
2809 * Meeting with the French group :WORK:
2810 ** Summary by Frank :BOSS:NOTES:
2811 *** TODO Prepare slides for him :ACTION:
2813 the final heading will have the tags `:WORK:', `:BOSS:', `:NOTES:', and
2814 `:ACTION:'. When executing tag searches and Org-mode finds that a
2815 certain headline matches the search criterion, it will not check any
2816 sublevel headline, assuming that these likely also match, and that the
2817 list of matches can become very long. This may not be what you want,
2818 however, and you can influence inheritance and searching using the
2819 variables `org-use-tag-inheritance' and `org-tags-match-list-sublevels'.
2822 File: org, Node: Setting tags, Next: Tag searches, Prev: Tag inheritance, Up: Tags
2827 Tags can simply be typed into the buffer at the end of a headline.
2828 After a colon, `M-<TAB>' offers completion on tags. There is also a
2829 special command for inserting tags:
2832 Enter new tags for the current headline. Org-mode will either
2833 offer completion or a special single-key interface for setting
2834 tags, see below. After pressing <RET>, the tags will be inserted
2835 and aligned to `org-tags-column'. When called with a `C-u'
2836 prefix, all tags in the current buffer will be aligned to that
2837 column, just to make things look nice. TAGS are automatically
2838 realigned after promotion, demotion, and TODO state changes (*note
2841 Org will support tag insertion based on a _list of tags_. By
2842 default this list is constructed dynamically, containing all tags
2843 currently used in the buffer. You may also globally specify a hard list
2844 of tags with the variable `org-tag-alist'. Finally you can set the
2845 default tags for a given file with lines like
2847 #+TAGS: @WORK @HOME @TENNISCLUB
2848 #+TAGS: Laptop Car PC Sailboat
2850 If you have globally defined your preferred set of tags using the
2851 variable `org-tag-alist', but would like to use a dynamic tag list in a
2852 specific file: Just add an empty TAGS option line to that file:
2856 The default support method for entering tags is minibuffer
2857 completion. However, Org-mode also implements a much better method:
2858 _fast tag selection_. This method allows to select and deselect tags
2859 with a single key per tag. To function efficiently, you should assign
2860 unique keys to most tags. This can be done globally with
2862 (setq org-tag-alist '(("@WORK" . ?w) ("@HOME" . ?h) ("Laptop" . ?l)))
2864 or on a per-file basis with
2866 #+TAGS: @WORK(w) @HOME(h) @TENNISCLUB(t) Laptop(l) PC(p)
2868 You can also group together tags that are mutually exclusive. With
2871 #+TAGS: { @WORK(w) @HOME(h) @TENNISCLUB(t) } Laptop(l) PC(p)
2873 you indicate that at most one of `@WORK', `@HOME', and `@TENNISCLUB'
2876 Don't forget to press `C-c C-c' with the cursor in one of these lines
2877 to activate any changes.
2879 If at least one tag has a selection key, pressing `C-c C-c' will
2880 automatically present you with a special interface, listing inherited
2881 tags, the tags of the current headline, and a list of all legal tags
2882 with corresponding keys(2). In this interface, you can use the
2886 Pressing keys assigned to tags will add or remove them from the
2887 list of tags in the current line. Selecting a tag in a group of
2888 mutually exclusive tags will turn off any other tags from that
2892 Enter a tag in the minibuffer, even if the tag is not in the
2893 predefined list. You will be able to complete on all tags present
2897 Clear all tags for this line.
2900 Accept the modified set.
2903 Abort without installing changes.
2906 If `q' is not assigned to a tag, it aborts like `C-g'.
2909 Turn off groups of mutually exclusive tags. Use this to (as an
2910 exception) assign several tags from such a group.
2913 Toggle auto-exit after the next change (see below). If you are
2914 using expert mode, the first `C-c' will display the selection
2917 This method lets you assign tags to a headline with very few keys. With
2918 the above setup, you could clear the current tags and set `@HOME',
2919 `Laptop' and `PC' tags with just the following keys: `C-c C-c <SPC> h l
2920 p <RET>'. Switching from `@HOME' to `@WORK' would be done with `C-c
2921 C-c w <RET>' or alternatively with `C-c C-c C-c w'. Adding the
2922 non-predefined tag `Sarah' could be done with `C-c C-c <TAB> S a r a h
2925 If you find that most of the time, you need only a single keypress to
2926 modify your list of tags, set the variable
2927 `org-fast-tag-selection-single-key'. Then you no longer have to press
2928 <RET> to exit fast tag selection - it will immediately exit after the
2929 first change. If you then occasionally need more keys, press `C-c' to
2930 turn off auto-exit for the current tag selection process (in effect:
2931 start selection with `C-c C-c C-c' instead of `C-c C-c'). If you set
2932 the variable to the value `expert', the special window is not even
2933 shown for single-key tag selection, it comes up only when you press an
2936 ---------- Footnotes ----------
2938 (1) In `org-mode-alist' use `'(:startgroup)' and `'(:endgroup)',
2939 respectively. Several groups are allowed.
2941 (2) Keys will automatically be assigned to tags which have no
2945 File: org, Node: Tag searches, Prev: Setting tags, Up: Tags
2950 Once a tags system has been set up, it can be used to collect related
2951 information into special lists.
2954 Create a sparse tree with all headlines matching a tags search.
2955 With a `C-u' prefix argument, ignore headlines that are not a TODO
2959 Create a global list of tag matches from all agenda files. *Note
2960 Matching tags and properties::.
2963 Create a global list of tag matches from all agenda files, but
2964 check only TODO items and force checking subitems (see variable
2965 `org-tags-match-list-sublevels').
2967 A tags search string can use Boolean operators `&' for AND and `|'
2968 for OR. `&' binds more strongly than `|'. Parenthesis are currently
2969 not implemented. A tag may also be preceded by `-', to select against
2970 it, and `+' is syntactic sugar for positive selection. The AND
2971 operator `&' is optional when `+' or `-' is present. Examples:
2974 Select headlines tagged `:WORK:', but discard those also tagged
2978 Selects lines tagged `:WORK:' or `:LAPTOP:'.
2981 Like before, but require the `:LAPTOP:' lines to be tagged also
2984 If you are using multi-state TODO keywords (*note TODO
2985 extensions::), it can be useful to also match on the TODO keyword.
2986 This can be done by adding a condition after a slash to a tags match.
2987 The syntax is similar to the tag matches, but should be applied with
2988 consideration: For example, a positive selection on several TODO
2989 keywords can not meaningfully be combined with boolean AND. However,
2990 _negative selection_ combined with AND can be meaningful. To make sure
2991 that only lines are checked that actually have any TODO keyword, use
2992 `C-c a M', or equivalently start the todo part after the slash with `!'.
2996 Select `:WORK:'-tagged TODO lines with the specific TODO keyword
2999 `WORK/!-WAITING-NEXT'
3000 Select `:WORK:'-tagged TODO lines that are neither `WAITING' nor
3003 `WORK/+WAITING|+NEXT'
3004 Select `:WORK:'-tagged TODO lines that are either `WAITING' or
3007 Any element of the tag/todo match can be a regular expression - in
3008 this case it must be enclosed in curly braces. For example,
3009 `WORK+{^BOSS.*}' matches headlines that contain the tag `WORK' and any
3010 tag starting with `BOSS'.
3012 You can also require a headline to be of a certain level, by writing
3013 instead of any TAG an expression like `LEVEL=3'. For example, a search
3014 `+LEVEL=3+BOSS/-DONE' lists all level three headlines that have the tag
3015 BOSS and are _not_ marked with the todo keyword DONE.
3018 File: org, Node: Properties and columns, Next: Timestamps, Prev: Tags, Up: Top
3020 7 Properties and Columns
3021 ************************
3023 Properties are a set of key-value pairs associated with an entry. There
3024 are two main applications for properties in Org-mode. First, properties
3025 are like tags, but with a value. For example, in a file where you
3026 document bugs and plan releases of a piece of software, instead of using
3027 tags like `:release_1:', `:release_2:', it can be more efficient to use
3028 a property `RELEASE' with a value `1.0' or `2.0'. Second, you can use
3029 properties to implement (very basic) database capabilities in an
3030 Org-mode buffer, for example to create a list of Music CD's you own.
3031 You can edit and view properties conveniently in column view (*note
3036 * Property syntax:: How properties are spelled out
3037 * Special properties:: Access to other Org-mode features
3038 * Property searches:: Matching property values
3039 * Column view:: Tabular viewing and editing
3040 * Property API:: Properties for Lisp programmers
3043 File: org, Node: Property syntax, Next: Special properties, Prev: Properties and columns, Up: Properties and columns
3048 Properties are key-value pairs. They need to be inserted into a special
3049 drawer (*note Drawers::) with the name `PROPERTIES'. Each property is
3050 specified on a single line, with the key (surrounded by colons) first,
3051 and the value after it. Here is an example:
3055 *** Goldberg Variations
3057 :Title: Goldberg Variations
3058 :Composer: J.S. Bach
3060 :Publisher: Deutsche Grammphon
3064 You may define the allowed values for a particular property `XYZ' by
3065 setting a property `XYZ_ALL'. This special property is _inherited_, so
3066 if you set it in a level 1 entry, it will apply to the entire tree.
3067 When allowed values are defined, setting the corresponding property
3068 becomes easier and is less prone to typing errors. For the example
3069 with the CD collection, we can predefine publishers and the number of
3070 disks in a box like this:
3074 :NDisks_ALL: 1 2 3 4
3075 :Publisher_ALL: "Deutsche Grammophon" Phillips EMI
3078 The following commands help to work with properties:
3081 After an initial colon in a line, complete property keys. All
3082 keys used in the current file will be offered as possible
3085 `M-x org-insert-property-drawer'
3086 Insert a property drawer into the current entry. The drawer will
3087 be inserted early in the entry, but after the lines with planning
3088 information like deadlines.
3091 With the cursor in a property drawer, this executes property
3095 Set a property in the current entry. Both the property and the
3096 value can be inserted using completion.
3099 Switch property at point to the next/previous allowed value.
3102 Remove a property from the current entry.
3105 Globally remove a property, from all entries in the current file.
3108 File: org, Node: Special properties, Next: Property searches, Prev: Property syntax, Up: Properties and columns
3110 7.2 Special Properties
3111 ======================
3113 Special properties provide alternative access method to Org-mode
3114 features discussed in the previous chapters, like the TODO state or the
3115 priority of an entry. This interface exists so that you can include
3116 these states into columns view (*note Column view::). The following
3117 property names are special and should not be used as keys in the
3120 TODO The TODO keyword of the entry.
3121 TAGS The tags defined directly in the headline.
3122 ALLTAGS All tags, including inherited ones.
3123 PRIORITY The priority of the entry, a string with a single letter.
3124 DEADLINE The deadline time string, without the angular brackets.
3125 SCHEDULED The scheduling time stamp, without the angular brackets.
3128 File: org, Node: Property searches, Next: Column view, Prev: Special properties, Up: Properties and columns
3130 7.3 Property searches
3131 =====================
3133 To create sparse trees and special lists with selection based on
3134 properties, the same commands are used as for tag searches (*note Tag
3135 searches::), and the same logic applies. For example, a search string
3137 +WORK-BOSS+PRIORITY="A"+coffee="unlimited"+with={Sarah\|Denny}
3139 finds entries tagged `:WORK:' but not `:BOSS:', which also have a
3140 priority value `A', a `:coffee:' property with the value `unlimited',
3141 and a `:with:' property that is matched by the regular expression
3145 File: org, Node: Column view, Next: Property API, Prev: Property searches, Up: Properties and columns
3150 A great way to view and edit properties in aan outline tree is _column
3151 view_. In column view, each outline item is turned into a table row.
3152 Columns in this table provide access to properties of the entries.
3153 Org-mode implements columns by overlaying a tabular structure over the
3154 headline of each item. While the headlines have been turned into a
3155 table row, you can still change the visibility of the outline tree.
3156 For example, you get a compact table by switching to CONTENTS view
3157 (`S-<TAB> S-<TAB>', or simple `c' while column view is active), but you
3158 can still open, read, and edit the entry below each headline. Or, you
3159 can switch to column view after executing a sparse tree command and in
3160 this way get a table only for the selected items. Column view also
3161 works in agenda buffers (*note Agenda views::) where queries have
3162 collected selected items, possibly from a number of files.
3166 * Defining columns:: The COLUMNS format property
3167 * Using column view:: How to create and use column view
3170 File: org, Node: Defining columns, Next: Using column view, Prev: Column view, Up: Column view
3172 7.4.1 Defining Columns
3173 ----------------------
3175 Setting up a column view first requires defining the columns. This is
3176 done by defining a column format line.
3180 * Scope of column definitions:: Where defined, where valid?
3181 * Column attributes:: Appearance and content of a column
3184 File: org, Node: Scope of column definitions, Next: Column attributes, Prev: Defining columns, Up: Defining columns
3186 7.4.1.1 Scope of column definitions
3187 ...................................
3189 To define a column format for an entire file, use a line like
3191 #+COLUMNS: %25ITEM %TAGS %PRIORITY %TODO
3193 To specify a format that only applies to a specific tree, add a
3194 COLUMNS property to the top node of that tree, for example
3195 ** Top node for columns view
3197 :COLUMNS: %25ITEM %TAGS %PRIORITY %TODO
3200 If a `COLUMNS' property is present in an entry, it defines columns
3201 for the entry itself, and for the entire subtree below it. Since the
3202 column definition is part of the hierarchical structure of the document,
3203 you can define columns on level 1 that are general enough for all
3204 sublevels, and more specific columns further down, when you edit a
3205 deeper part of the tree.
3208 File: org, Node: Column attributes, Prev: Scope of column definitions, Up: Defining columns
3210 7.4.1.2 Column attributes
3211 .........................
3213 A column definition sets the attributes of a column. The general
3214 definition looks like this:
3216 %[width]property[(title)][{summary-type}]
3218 Except for the percent sign and the property name, all items are
3219 optional. The individual parts have the following meaning:
3221 width An integer specifying the width of the column in characters.
3222 If omitted, the width will be determined automatically.
3223 property The property that should be edited in this column.
3224 (title) The header text for the column. If omitted, the
3225 property name is used.
3226 {summary-type} The summary type. If specified, the column values for
3227 parent nodes are computed from the children.
3228 Supported summary types are:
3229 {+} Sum numbers in this column.
3230 {:} Sum times, HH:MM:SS, plain numbers are hours.
3231 {X} Checkbox status, [X] if all children are [X].
3233 Here is an example for a complete columns definition, along with allowed
3236 :COLUMNS: %20ITEM %9Approved(Approved?){X} %Owner %11Status %10Time_Spent{:}
3237 :Owner_ALL: Tammy Mark Karl Lisa Don
3238 :Status_ALL: "In progress" "Not started yet" "Finished" ""
3239 :Approved_ALL: "[ ]" "[X]"
3241 The first column, `%25ITEM', means the first 25 characters of the
3242 item itself, i.e. of the headline. You probably always should start the
3243 column definition with the ITEM specifier. The other specifiers create
3244 columns `Owner' with a list of names as allowed values, for `Status'
3245 with four different possible values, and for a checkbox field
3246 `Approved'. When no width is given after the `%' character, the column
3247 will be exactly as wide as it needs to be in order to fully display all
3248 values. The `Approved' column does have a modified title (`Approved?',
3249 with a question mark). Summaries will be created for the `Time_Spent'
3250 column by adding time duration expressions like HH:MM, and for the
3251 `Approved' column, by providing an `[X]' status if all children have
3255 File: org, Node: Using column view, Prev: Defining columns, Up: Column view
3257 7.4.2 Using Column View
3258 -----------------------
3260 Turning column view on and off
3261 ..............................
3264 Create the column view for the local environment. This command
3265 searches the hierarchy, up from point, for a `COLUMNS' property
3266 that defines a format. When one is found, the column view table
3267 is established for the entire tree, starting from the entry that
3268 contains the `COLUMNS' property. If none is found, the format is
3269 taken from the `#+COLUMNS' line or from the variable
3270 `org-columns-default-format', and column view is established for
3271 the current entry and its subtree.
3279 `<left> <right> <up> <down>'
3280 Move through the column view from field to field.
3283 Switch to the next/previous allowed value of the field. For this,
3284 you have to have specified allowed values for a property.
3287 Same as `S-<left>/<right>'
3290 Edit the property at point. For the special properties, this will
3291 invoke the same interface that you normally use to change that
3292 property. For example, when editing a TAGS property, the tag
3293 completion or fast selection interface will pop up.
3296 View the full value of this property. This is useful if the width
3297 of the column is smaller than that of the value.
3300 Edit the list of allowed values for this property. If the list is
3301 found in the hierarchy, the modified values is stored there. If
3302 no list is found, the new value is stored in the first entry that
3303 is part of the current column view.
3305 Modifying the table structure
3306 .............................
3309 Make the column narrower/wider by one character.
3312 Insert a new column, to the right of the current column.
3315 Delete the current column.
3318 File: org, Node: Property API, Prev: Column view, Up: Properties and columns
3320 7.5 The Property API
3321 ====================
3323 There is a full API for accessing and changing properties. This API can
3324 be used by Emacs Lisp programs to work with properties and to implement
3325 features based on them. For more information see *Note Using the
3329 File: org, Node: Timestamps, Next: Agenda views, Prev: Properties and columns, Up: Top
3334 Items can be labeled with timestamps to make them useful for project
3339 * Time stamps:: Assigning a time to a tree entry
3340 * Creating timestamps:: Commands which insert timestamps
3341 * Deadlines and scheduling:: Planning your work
3342 * Progress logging:: Documenting when what work was done.
3345 File: org, Node: Time stamps, Next: Creating timestamps, Prev: Timestamps, Up: Timestamps
3347 8.1 Time stamps, deadlines and scheduling
3348 =========================================
3350 A time stamp is a specification of a date (possibly with time or a range
3351 of times) in a special format, either `<2003-09-16 Tue>' or
3352 `<2003-09-16 Tue 09:39>' or `<2003-09-16 Tue 12:00-12:30>'(1). A time
3353 stamp can appear anywhere in the headline or body of an org-tree entry.
3354 Its presence causes entries to be shown on specific dates in the agenda
3355 (*note Weekly/Daily agenda::). We distinguish:
3358 A simple time stamp just assigns a date/time to an item. This is
3359 just like writing down an appointment in a paper agenda, or like
3360 writing down an event in a diary, when you want to take note of
3361 when something happened. In the timeline and agenda displays, the
3362 headline of an entry associated with a plain time stamp will be
3363 shown exactly on that date.
3365 * Meet Peter at the movies <2006-11-01 Wed 19:15>
3366 * Discussion on climate change <2006-11-02 Thu 20:00-22:00>
3368 TIME STAMP WITH REPEATER INTERVAL
3369 A time stamp may contain a _repeater interval_, indicating that it
3370 applies not only on the given date, but again and again after a
3371 certain interval of N days (d), weeks (w), months(m), or years(y).
3372 The following will show up in the agenda every Wednesday:
3374 * Pick up Sam at school <2007-05-16 Wed 12:30 +1w>
3376 DIARY-STYLE SEXP ENTRIES
3377 For more complex date specifications, Org-mode supports using the
3378 special sexp diary entries implemented in the Emacs calendar/diary
3379 package. For example
3381 * The nerd meeting on every 2nd Thursday of the month
3382 <%%(diary-float t 4 2)>
3385 Two time stamps connected by `--' denote a range. The headline
3386 will be shown on the first and last day of the range, and on any
3387 dates that are displayed and fall in the range. Here is an
3390 ** Meeting in Amsterdam
3391 <2004-08-23 Mon>--<2004-08-26 Thu>
3394 Just like a plain time stamp, but with square brackets instead of
3395 angular ones. These time stamps are inactive in the sense that
3396 they do _not_ trigger an entry to show up in the agenda.
3398 * Gillian comes late for the fifth time [2006-11-01 Wed]
3401 ---------- Footnotes ----------
3403 (1) This is the standard ISO date/time format. If you cannot get
3404 used to these, see *Note Custom time format::
3407 File: org, Node: Creating timestamps, Next: Deadlines and scheduling, Prev: Time stamps, Up: Timestamps
3409 8.2 Creating timestamps
3410 =======================
3412 For Org-mode to recognize time stamps, they need to be in the specific
3413 format. All commands listed below produce time stamps in the correct
3417 Prompt for a date and insert a corresponding time stamp. When the
3418 cursor is at a previously used time stamp, it is updated to NOW.
3419 When this command is used twice in succession, a time range is
3423 Like `C-c .', but use the alternative format which contains date
3424 and time. The default time can be rounded to multiples of 5
3425 minutes, see the option `org-time-stamp-rounding-minutes'.
3428 Like `C-c .', but insert an inactive time stamp that will not cause
3432 Insert a time stamp corresponding to the cursor date in the
3436 Access the Emacs calendar for the current date. If there is a
3437 timestamp in the current line, goto the corresponding date instead.
3440 Access the agenda for the date given by the time stamp or -range at
3441 point (*note Weekly/Daily agenda::).
3445 Change date at cursor by one day. These key bindings conflict with
3446 CUA-mode (*note Conflicts::).
3450 Change the item under the cursor in a timestamp. The cursor can
3451 be on a year, month, day, hour or minute. Note that if the cursor
3452 is in a headline and not at a time stamp, these same keys modify
3453 the priority of an item. (*note Priorities::). The key bindings
3454 also conflict with CUA-mode (*note Conflicts::).
3457 Evaluate a time range by computing the difference between start and
3458 end. With prefix arg, insert result after the time range (in a
3459 table: into the following column).
3463 * The date/time prompt:: How org-mode helps you entering date and time
3464 * Custom time format:: Making dates look differently
3467 File: org, Node: The date/time prompt, Next: Custom time format, Prev: Creating timestamps, Up: Creating timestamps
3469 8.2.1 The date/time prompt
3470 --------------------------
3472 When Org-mode prompts for a date/time, the prompt suggests to enter an
3473 ISO date. But it will in fact accept any string containing some date
3474 and/or time information. You can, for example, use `C-y' to paste a
3475 (possibly multi-line) string copied from an email message. Org-mode
3476 will find whatever information is in there and will replace anything not
3477 specified with the current date and time. For example:
3479 3-2-5 --> 2003-02-05
3480 feb 15 --> currentyear-02-15
3481 sep 12 9 --> 2009-09-12
3482 12:45 --> today 12:45
3483 22 sept 0:34 --> currentyear-09-22 0:34
3484 12 --> currentyear-currentmonth-12
3485 Fri --> nearest Friday (today or later)
3486 +4 --> 4 days from now (if +N is the only thing given)
3488 The function understands English month and weekday abbreviations. If
3489 you want to use unabbreviated names and/or other languages, configure
3490 the variables `parse-time-months' and `parse-time-weekdays'.
3492 Parallel to the minibuffer prompt, a calendar is popped up(1). When
3493 you exit the date prompt, either by clicking on a date in the calendar,
3494 or by pressing <RET>, the date selected in the calendar will be
3495 combined with the information entered at the prompt. You can control
3496 the calendar fully from the minibuffer:
3499 Scroll calendar backwards by one month.
3502 Scroll calendar forwards by one month.
3505 Select date by clicking on it.
3526 Choose date in calendar (only if nothing was typed into
3529 ---------- Footnotes ----------
3531 (1) If you don't need/want the calendar, configure the variable
3532 `org-popup-calendar-for-date-prompt'.
3535 File: org, Node: Custom time format, Prev: The date/time prompt, Up: Creating timestamps
3537 8.2.2 Custom time format
3538 ------------------------
3540 Org-mode uses the standard ISO notation for dates and times as it is
3541 defined in ISO 8601. If you cannot get used to this and require another
3542 representation of date and time to keep you happy, you can get it by
3543 customizing the variables `org-display-custom-times' and
3544 `org-time-stamp-custom-formats'.
3547 Toggle the display of custom formats for dates and times.
3549 Org-mode needs the default format for scanning, so the custom date/time
3550 format does not _replace_ the default format - instead it is put _over_
3551 the default format using text properties. This has the following
3553 * You cannot place the cursor onto a time stamp anymore, only before
3556 * The `S-<up>/<down>' keys can no longer be used to adjust each
3557 component of a time stamp. If the cursor is at the beginning of
3558 the stamp, `S-<up>/<down>' will change the stamp by one day, just
3559 like `S-<left>/<right>'. At the end of the stamp, the time will
3560 be changed by one minute.
3562 * If the time stamp contains a range of clock times or a repeater,
3563 these will not be overlayed, but remain in the buffer as they were.
3565 * When you delete a time stamp character-by-character, it will only
3566 disappear from the buffer after _all_ (invisible) characters
3567 belonging to the ISO timestamp have been removed.
3569 * If the custom time stamp format is longer than the default and you
3570 are using dates in tables, table alignment will be messed up. If
3571 the custom format is shorter, things do work as expected.
3574 File: org, Node: Deadlines and scheduling, Next: Progress logging, Prev: Creating timestamps, Up: Timestamps
3576 8.3 Deadlines and Scheduling
3577 ============================
3579 A time stamp may be preceded by special keywords to facilitate planning
3583 The task (most likely a TODO item) is supposed to be finished on
3584 that date, and it will be listed then. In addition, the
3585 compilation for _today_ will carry a warning about the approaching
3586 or missed deadline, starting `org-deadline-warning-days' before
3587 the due date, and continuing until the entry is marked DONE. An
3590 *** TODO write article about the Earth for the Guide
3591 The editor in charge is [[bbdb:Ford Prefect]]
3592 DEADLINE: <2004-02-29 Sun>
3595 You are planning to start working on that task on the given date.
3596 The headline will be listed under the given date(1). In addition,
3597 a reminder that the scheduled date has passed will be present in
3598 the compilation for _today_, until the entry is marked DONE.
3599 I.e., the task will automatically be forwarded until completed.
3601 *** TODO Call Trillian for a date on New Years Eve.
3602 SCHEDULED: <2004-12-25 Sat>
3606 * Inserting deadline/schedule::
3609 ---------- Footnotes ----------
3611 (1) It will still be listed on that date after it has been marked
3612 DONE. If you don't like this, set the variable
3613 `org-agenda-skip-scheduled-if-done'.
3616 File: org, Node: Inserting deadline/schedule, Next: Repeated tasks, Prev: Deadlines and scheduling, Up: Deadlines and scheduling
3618 8.3.1 Inserting deadline/schedule
3619 ---------------------------------
3621 The following commands allow to quickly insert a deadline or to schedule
3625 Insert `DEADLINE' keyword along with a stamp. The insertion will
3626 happen in the line directly following the headline.
3629 Create a sparse tree with all deadlines that are either past-due,
3630 or which will become due within `org-deadline-warning-days'. With
3631 `C-u' prefix, show all deadlines in the file. With a numeric
3632 prefix, check that many days. For example, `C-1 C-c C-w' shows
3633 all deadlines due tomorrow.
3636 Insert `SCHEDULED' keyword along with a stamp. The insertion will
3637 happen in the line directly following the headline. Any CLOSED
3638 timestamp will be removed.
3641 File: org, Node: Repeated tasks, Prev: Inserting deadline/schedule, Up: Deadlines and scheduling
3643 8.3.2 Repeated Tasks
3644 --------------------
3646 Some tasks need to be repeated again and again, and Org-mode therefore
3647 allows to use a repeater in a DEADLINE or SCHEDULED time stamp, for
3649 ** TODO Pay the rent
3650 DEADLINE: <2005-10-01 Sat +1m>
3652 Deadlines and scheduled items produce entries in the agenda when they
3653 are over-due, so it is important to be able to mark such an entry as
3654 completed once you have done so. When you mark a DEADLINE or a SCHEDULE
3655 with the todo keyword DONE, it will no longer produce entries in the
3656 agenda. The problem with this is, however, that then also the _next_
3657 instance of the repeated entry will not be active. Org-mode deals with
3658 this in the following way: When you try to mark such an entry DONE
3659 (using `C-c C-t'), it will shift the base date of the repeating time
3660 stamp by the repeater interval, and immediately set the entry state
3661 back to TODO. In the example above, setting the state to DONE would
3662 actually switch the date like this:
3664 ** TODO Pay the rent
3665 DEADLINE: <2005-11-01 Tue +1m>
3667 You will also be prompted for a note that will be put under the
3668 DEADLINE line to keep a record that you actually acted on the previous
3669 instance of this deadline.
3671 As a consequence of shifting the base date, this entry will no
3672 longer be visible in the agenda when checking past dates, but all
3673 future instances will be visible.
3675 You may have both scheduling and deadline information for a specific
3676 task - just make sure that the repeater intervals on both are the same.
3679 File: org, Node: Progress logging, Prev: Deadlines and scheduling, Up: Timestamps
3681 8.4 Progress Logging
3682 ====================
3684 Org-mode can automatically record a time stamp when you mark a TODO item
3685 as DONE, or even each time when you change the state of a TODO item.
3686 You can also measure precisely the time you spent on specific items in a
3687 project by starting and stopping a clock when you start and stop working
3688 on an aspect of a project.
3692 * Closing items:: When was this entry marked DONE?
3693 * Tracking TODO state changes:: When did the status change?
3694 * Clocking work time:: When exactly did you work on this item?
3697 File: org, Node: Closing items, Next: Tracking TODO state changes, Prev: Progress logging, Up: Progress logging
3702 If you want to keep track of _when_ a certain TODO item was finished,
3703 turn on logging with(1)
3705 (setq org-log-done t)
3707 Then each time you turn a TODO entry into DONE using either `C-c C-t'
3708 in the Org-mode buffer or `t' in the agenda buffer, a line `CLOSED:
3709 [timestamp]' will be inserted just after the headline. If you turn the
3710 entry back into a TODO item through further state cycling, that line
3711 will be removed again. In the timeline (*note Timeline::) and in the
3712 agenda (*note Weekly/Daily agenda::), you can then use the `l' key to
3713 display the TODO items closed on each day, giving you an overview of
3714 what has been done on a day. If you want to record a note along with
3715 the timestamp, use(2)
3717 (setq org-log-done '(done))
3719 ---------- Footnotes ----------
3721 (1) The corresponding in-buffer setting is: `#+STARTUP: logdone'
3723 (2) The corresponding in-buffer setting is: `#+STARTUP: lognotedone'
3726 File: org, Node: Tracking TODO state changes, Next: Clocking work time, Prev: Closing items, Up: Progress logging
3728 8.4.2 Tracking TODO state changes
3729 ---------------------------------
3731 When TODO keywords are used as workflow states (*note Workflow
3732 states::), you might want to keep track of when a state change occurred,
3733 and you may even want to attach notes to that state change. With the
3736 (setq org-log-done '(state))
3738 each state change will prompt you for a note that will be attached to
3739 the current headline. Very likely you do not want this verbose tracking
3740 all the time, so it is probably better to configure this behavior with
3741 in-buffer options. For example, if you are tracking purchases, put
3742 these into a separate file that starts with:
3744 #+SEQ_TODO: TODO ORDERED INVOICE PAYED RECEIVED SENT
3745 #+STARTUP: lognotestate
3748 File: org, Node: Clocking work time, Prev: Tracking TODO state changes, Up: Progress logging
3750 8.4.3 Clocking work time
3751 ------------------------
3753 Org-mode allows you to clock the time you spent on specific tasks in a
3754 project. When you start working on an item, you can start the clock.
3755 When you stop working on that task, or when you mark the task done, the
3756 clock is stopped and the corresponding time interval is recorded. It
3757 also computes the total time spent on each subtree of a project.
3760 Start the clock on the current item (clock-in). This inserts the
3761 CLOCK keyword together with a timestamp.
3764 Stop the clock (clock-out). The inserts another timestamp at the
3765 same location where the clock was last started. It also directly
3766 computes the resulting time in inserts it after the time range as
3767 `=> HH:MM'. See the variable `org-log-done' for the possibility to
3768 record an additional note together with the clock-out time
3772 Recompute the time interval after changing one of the time stamps.
3773 This is only necessary if you edit the time stamps directly. If
3774 you change them with `S-<cursor>' keys, the update is automatic.
3777 Changing the TODO state of an item to DONE automatically stops the
3778 clock if it is running in this same item.
3781 Cancel the current clock. This is useful if a clock was started by
3782 mistake, or if you ended up working on something else.
3785 Display time summaries for each subtree in the current buffer.
3786 This puts overlays at the end of each headline, showing the total
3787 time recorded under that heading, including the time of any
3788 subheadings. You can use visibility cycling to study the tree, but
3789 the overlays disappear when you change the buffer (see variable
3790 `org-remove-highlights-with-change') or press `C-c C-c'.
3793 Insert a dynamic block (*note Dynamic blocks::) containing a clock
3794 report as an org-mode table into the current file.
3795 #+BEGIN: clocktable :maxlevel 2 :emphasize nil
3798 If such a block already exists, its content is replaced by the new
3799 table. The `BEGIN' line can specify options:
3800 :maxlevels Maximum level depth to which times are listed in the table.
3801 :emphasize When `t', emphasize level one and level two items
3802 :block The time block to consider. This block is specified relative
3803 to the current time and may be any of these keywords:
3804 `today', `yesterday', `thisweek', `lastweek',
3805 `thismonth', `lastmonth', `thisyear', or `lastyear'.
3806 :tstart A time string specifying when to start considering times
3807 :tend A time string specifying when to stop considering times
3808 So to get a clock summary for the current day, you could write
3809 #+BEGIN: clocktable :maxlevel 2 :block today
3812 and to use a specific time range you could write(2)
3813 #+BEGIN: clocktable :tstart "<2006-08-10 Thu 10:00>"
3814 :tend "<2006-08-10 Thu 12:00>"
3819 Update all dynamic blocks (*note Dynamic blocks::). This is
3820 useful if you have several clocktable blocks in a buffer.
3822 The `l' key may be used in the timeline (*note Timeline::) and in
3823 the agenda (*note Weekly/Daily agenda::) to show which tasks have been
3824 worked on or closed during a day.
3826 ---------- Footnotes ----------
3828 (1) The corresponding in-buffer setting is: `#+STARTUP:
3831 (2) Note that all parameters must be specified in a single line -
3832 the line is broken here only to fit it onto the manual.
3835 File: org, Node: Agenda views, Next: Embedded LaTeX, Prev: Timestamps, Up: Top
3840 Due to the way Org-mode works, TODO items, time-stamped items, and
3841 tagged headlines can be scattered throughout a file or even a number of
3842 files. To get an overview over open action items, or over events that
3843 are important for a particular date, this information must be collected,
3844 sorted and displayed in an organized way.
3846 Org-mode can select items based on various criteria, and display them
3847 in a separate buffer. Six different view types are provided:
3849 * an _agenda_ that is like a calendar and shows information for
3852 * a _TODO list_ that covers all unfinished action items,
3854 * a _tags view_, showings headlines based on the tags associated
3857 * a _timeline view_ that shows all events in a single Org-mode file,
3858 in time-sorted view,
3860 * a _stuck projects view_ showing projects that currently don't move
3863 * _custom views_ that are special tag/keyword searches and
3864 combinations of different views.
3866 The extracted information is displayed in a special _agenda buffer_.
3867 This buffer is read-only, but provides commands to visit the
3868 corresponding locations in the original Org-mode files, and even to
3869 edit these files remotely.
3871 Two variables control how the agenda buffer is displayed and whether
3872 the window configuration is restored when the agenda exits:
3873 `org-agenda-window-setup' and `org-agenda-restore-windows-after-quit'.
3877 * Agenda files:: Files being searched for agenda information
3878 * Agenda dispatcher:: Keyboard access to agenda views
3879 * Built-in agenda views:: What is available out of the box?
3880 * Presentation and sorting:: How agenda items are prepared for display
3881 * Agenda commands:: Remote editing of org trees
3882 * Custom agenda views:: Defining special searches and views
3885 File: org, Node: Agenda files, Next: Agenda dispatcher, Prev: Agenda views, Up: Agenda views
3890 The information to be shown is collected from all _agenda files_, the
3891 files listed in the variable `org-agenda-files'(1). Thus even if you
3892 only work with a single Org-mode file, this file should be put into
3893 that list(2). You can customize `org-agenda-files', but the easiest
3894 way to maintain it is through the following commands
3897 Add current file to the list of agenda files. The file is added to
3898 the front of the list. If it was already in the list, it is moved
3899 to the front. With prefix arg, file is added/moved to the end.
3902 Remove current file from the list of agenda files.
3906 Cycle through agenda file list, visiting one file after the other.
3908 The Org menu contains the current list of files and can be used to
3911 ---------- Footnotes ----------
3913 (1) If the value of that variable is not a list, but a single file
3914 name, then the list of agenda files will be maintained in that external
3917 (2) When using the dispatcher, pressing `1' before selecting a
3918 command will actually limit the command to the current file, and ignore
3919 `org-agenda-files' until the next dispatcher command.
3922 File: org, Node: Agenda dispatcher, Next: Built-in agenda views, Prev: Agenda files, Up: Agenda views
3924 9.2 The agenda dispatcher
3925 =========================
3927 The views are created through a dispatcher that should be bound to a
3928 global key, for example `C-c a' (*note Installation::). In the
3929 following we will assume that `C-c a' is indeed how the dispatcher is
3930 accessed and list keyboard access to commands accordingly. After
3931 pressing `C-c a', an additional letter is required to execute a
3932 command. The dispatcher offers the following default commands:
3934 Create the calendar-like agenda (*note Weekly/Daily agenda::).
3937 Create a list of all TODO items (*note Global TODO list::).
3940 Create a list of headlines matching a TAGS expression (*note
3941 Matching tags and properties::).
3944 Create the timeline view for the current buffer (*note Timeline::).
3947 Create a list of stuck projects (*note Stuck projects::).
3950 Restrict an agenda command to the current buffer. After pressing
3951 `1', you still need to press the character selecting the command.
3954 If there is an active region, restrict the following agenda
3955 command to the region. Otherwise, restrict it to the current
3956 subtree. After pressing `0', you still need to press the
3957 character selecting the command.
3959 You can also define custom commands that will be accessible through
3960 the dispatcher, just like the default commands. This includes the
3961 possibility to create extended agenda buffers that contain several
3962 blocks together, for example the weekly agenda, the global TODO list and
3963 a number of special tags matches. *Note Custom agenda views::.
3966 File: org, Node: Built-in agenda views, Next: Presentation and sorting, Prev: Agenda dispatcher, Up: Agenda views
3968 9.3 The built-in agenda views
3969 =============================
3971 In this section we describe the built-in views.
3975 * Weekly/Daily agenda:: The calendar page with current tasks
3976 * Global TODO list:: All unfinished action items
3977 * Matching tags and properties:: Structured information with fine-tuned search
3978 * Timeline:: Time-sorted view for single file
3979 * Stuck projects:: Find projects you need to review
3982 File: org, Node: Weekly/Daily agenda, Next: Global TODO list, Prev: Built-in agenda views, Up: Built-in agenda views
3984 9.3.1 The weekly/daily agenda
3985 -----------------------------
3987 The purpose of the weekly/daily _agenda_ is to act like a page of a
3988 paper agenda, showing all the tasks for the current week or day.
3991 Compile an agenda for the current week from a list of org files.
3992 The agenda shows the entries for each day. With a `C-u' prefix (or
3993 when the variable `org-agenda-include-all-todo' is `t'), all
3994 unfinished TODO items (including those without a date) are also
3995 listed at the beginning of the buffer, before the first date.
3997 Remote editing from the agenda buffer means, for example, that you
3998 can change the dates of deadlines and appointments from the agenda
3999 buffer. The commands available in the Agenda buffer are listed in
4000 *Note Agenda commands::.
4002 Calendar/Diary integration
4003 ..........................
4005 Emacs contains the calendar and diary by Edward M. Reingold. The
4006 calendar displays a three-month calendar with holidays from different
4007 countries and cultures. The diary allows you to keep track of
4008 anniversaries, lunar phases, sunrise/set, recurrent appointments
4009 (weekly, monthly) and more. In this way, it is quite complementary to
4010 Org-mode. It can be very useful to combine output from Org-mode with
4013 In order to include entries from the Emacs diary into Org-mode's
4014 agenda, you only need to customize the variable
4016 (setq org-agenda-include-diary t)
4018 After that, everything will happen automatically. All diary entries
4019 including holidays, anniversaries etc will be included in the agenda
4020 buffer created by Org-mode. <SPC>, <TAB>, and <RET> can be used from
4021 the agenda buffer to jump to the diary file in order to edit existing
4022 diary entries. The `i' command to insert new entries for the current
4023 date works in the agenda buffer, as well as the commands `S', `M', and
4024 `C' to display Sunrise/Sunset times, show lunar phases and to convert
4025 to other calendars, respectively. `c' can be used to switch back and
4026 forth between calendar and agenda.
4028 If you are using the diary only for sexp entries and holidays, it is
4029 faster to not use the above setting, but instead to copy or even move
4030 the entries into an Org-mode file. Org-mode evaluates diary-style sexp
4031 entries, and does it faster because there is no overhead for first
4032 creating the diary display. Note that the sexp entries must start at
4033 the left margin, no white space is allowed before them. For example,
4034 the following segment of an Org-mode file will be processed and entries
4035 will be made in the agenda:
4037 * Birthdays and similar stuff
4039 %%(org-calendar-holiday) ; special function for holiday names
4041 %%(diary-anniversary 14 5 1956) Arthur Dent is %d years old
4042 %%(diary-anniversary 2 10 1869) Mahatma Gandhi would be %d years old
4045 File: org, Node: Global TODO list, Next: Matching tags and properties, Prev: Weekly/Daily agenda, Up: Built-in agenda views
4047 9.3.2 The global TODO list
4048 --------------------------
4050 The global TODO list contains all unfinished TODO items, formatted and
4051 collected into a single place.
4054 Show the global TODO list. This collects the TODO items from all
4055 agenda files (*note Agenda views::) into a single buffer. The
4056 buffer is in `agenda-mode', so there are commands to examine and
4057 manipulate the TODO entries directly from that buffer (*note
4061 Like the above, but allows selection of a specific TODO keyword.
4062 You can also do this by specifying a prefix argument to `C-c a t'.
4063 With a `C-u' prefix you are prompted for a keyword, and you may
4064 also specify several keywords by separating them with `|' as
4065 boolean OR operator. With a numeric prefix, the Nth keyword in
4066 `org-todo-keywords' is selected. The `r' key in the agenda buffer
4067 regenerates it, and you can give a prefix argument to this command
4068 to change the selected TODO keyword, for example `3 r'. If you
4069 often need a search for a specific keyword, define a custom
4070 command for it (*note Agenda dispatcher::).
4071 Matching specific TODO keywords can also be done as part of a tags
4072 search (*note Tag searches::).
4074 Remote editing of TODO items means that you can change the state of a
4075 TODO entry with a single key press. The commands available in the TODO
4076 list are described in *Note Agenda commands::.
4078 Normally the global todo list simply shows all headlines with TODO
4079 keywords. This list can become very long. There are two ways to keep
4081 - Some people view a TODO item that has been _scheduled_ for
4082 execution (*note Time stamps::) as no longer _open_. Configure the
4083 variable `org-agenda-todo-ignore-scheduled' to exclude scheduled
4084 items from the global TODO list.
4086 - TODO items may have sublevels to break up the task into subtasks.
4087 In such cases it may be enough to list only the highest level TODO
4088 headline and omit the sublevels from the global list. Configure
4089 the variable `org-agenda-todo-list-sublevels' to get this behavior.
4092 File: org, Node: Matching tags and properties, Next: Timeline, Prev: Global TODO list, Up: Built-in agenda views
4094 9.3.3 Matching Tags and Properties
4095 ----------------------------------
4097 If headlines in the agenda files are marked with _tags_ (*note Tags::),
4098 you can select headlines based on the tags that apply to them and
4099 collect them into an agenda buffer.
4102 Produce a list of all headlines that match a given set of tags.
4103 The command prompts for a selection criterion, which is a boolean
4104 logic expression with tags, like `+WORK+URGENT-WITHBOSS' or
4105 `WORK|HOME' (*note Tags::). If you often need a specific search,
4106 define a custom command for it (*note Agenda dispatcher::).
4109 Like `C-c a m', but only select headlines that are also TODO items
4110 and force checking subitems (see variable
4111 `org-tags-match-list-sublevels'). Matching specific todo keywords
4112 together with a tags match is also possible, see *Note Tag
4115 The commands available in the tags list are described in *Note
4119 File: org, Node: Timeline, Next: Stuck projects, Prev: Matching tags and properties, Up: Built-in agenda views
4121 9.3.4 Timeline for a single file
4122 --------------------------------
4124 The timeline summarizes all time-stamped items from a single Org-mode
4125 file in a _time-sorted view_. The main purpose of this command is to
4126 give an overview over events in a project.
4129 Show a time-sorted view of the org file, with all time-stamped
4130 items. When called with a `C-u' prefix, all unfinished TODO
4131 entries (scheduled or not) are also listed under the current date.
4133 The commands available in the timeline buffer are listed in *Note
4137 File: org, Node: Stuck projects, Prev: Timeline, Up: Built-in agenda views
4139 9.3.5 Stuck projects
4140 --------------------
4142 If you are following a system like David Allen's GTD to organize your
4143 work, one of the "duties" you have is a regular review to make sure
4144 that all projects move along. A _stuck_ project is a project that has
4145 no defined next actions, so it will never show up in the TODO lists
4146 Org-mode produces. During the review, you need to identify such
4147 projects and define next actions for them.
4150 List projects that are stuck.
4153 Customize the variable `org-stuck-projects' to define what a stuck
4154 project is and how to find it.
4156 You almost certainly will have to configure this view before it will
4157 work for you. The built-in default assumes that all your projects are
4158 level-2 headlines, and that a project is not stuck if it has at least
4159 one entry marked with a todo keyword TODO or NEXT or NEXTACTION.
4161 Lets assume that you, in your own way of using Org-mode, identify
4162 projects with a tag PROJECT, and that you use a todo keyword MAYBE to
4163 indicate a project that should not be considered yet. Lets further
4164 assume that the todo keyword DONE marks finished projects, and that NEXT
4165 and TODO indicate next actions. The tag @SHOP indicates shopping and
4166 is a next action even without the NEXT tag. Finally, if the project
4167 contains the special word IGNORE anywhere, it should not be listed
4168 either. In this case you would start by identifying eligible projects
4169 with a tags/todo match `+PROJECT/-MAYBE-DONE', and then check for TODO,
4170 NEXT, @SHOP, and IGNORE in the subtree to identify projects that are
4171 not stuck. The correct customization for this is
4173 (setq org-stuck-projects
4174 '("+PROJECT/-MAYBE-DONE" ("NEXT" "TODO") ("@SHOP")
4178 File: org, Node: Presentation and sorting, Next: Agenda commands, Prev: Built-in agenda views, Up: Agenda views
4180 9.4 Presentation and sorting
4181 ============================
4183 Before displaying items in an agenda view, Org-mode visually prepares
4184 the items and sorts them. Each item occupies a single line. The line
4185 starts with a _prefix_ that contains the _category_ (*note
4186 Categories::) of the item and other important information. You can
4187 customize the prefix using the option `org-agenda-prefix-format'. The
4188 prefix is followed by a cleaned-up version of the outline headline
4189 associated with the item.
4193 * Categories:: Not all tasks are equal
4194 * Time-of-day specifications:: How the agenda knows the time
4195 * Sorting of agenda items:: The order of things
4198 File: org, Node: Categories, Next: Time-of-day specifications, Prev: Presentation and sorting, Up: Presentation and sorting
4203 The category is a broad label assigned to each agenda item. By default,
4204 the category is simply derived from the file name, but you can also
4205 specify it with a special line in the buffer, like this:
4209 If there are several such lines in a file, each specifies the
4210 category for the text below it (but the first category also applies to
4211 any text before the first CATEGORY line). The display in the agenda
4212 buffer looks best if the category is not longer than 10 characters.
4215 File: org, Node: Time-of-day specifications, Next: Sorting of agenda items, Prev: Categories, Up: Presentation and sorting
4217 9.4.2 Time-of-Day Specifications
4218 --------------------------------
4220 Org-mode checks each agenda item for a time-of-day specification. The
4221 time can be part of the time stamp that triggered inclusion into the
4222 agenda, for example as in `<2005-05-10 Tue 19:00>'. Time ranges can be
4223 specified with two time stamps, like
4224 `<2005-05-10 Tue 20:30>--<2005-05-10 Tue 22:15>'.
4226 In the headline of the entry itself, a time(range) may also appear as
4227 plain text (like `12:45' or a `8:30-1pm'. If the agenda integrates the
4228 Emacs diary (*note Weekly/Daily agenda::), time specifications in diary
4229 entries are recognized as well.
4231 For agenda display, Org-mode extracts the time and displays it in a
4232 standard 24 hour format as part of the prefix. The example times in
4233 the previous paragraphs would end up in the agenda like this:
4235 8:30-13:00 Arthur Dent lies in front of the bulldozer
4236 12:45...... Ford Prefect arrives and takes Arthur to the pub
4237 19:00...... The Vogon reads his poem
4238 20:30-22:15 Marwin escorts the Hitchhikers to the bridge
4240 If the agenda is in single-day mode, or for the display of today, the
4241 timed entries are embedded in a time grid, like
4243 8:00...... ------------------
4244 8:30-13:00 Arthur Dent lies in front of the bulldozer
4245 10:00...... ------------------
4246 12:00...... ------------------
4247 12:45...... Ford Prefect arrives and takes Arthur to the pub
4248 14:00...... ------------------
4249 16:00...... ------------------
4250 18:00...... ------------------
4251 19:00...... The Vogon reads his poem
4252 20:00...... ------------------
4253 20:30-22:15 Marwin escorts the Hitchhikers to the bridge
4255 The time grid can be turned on and off with the variable
4256 `org-agenda-use-time-grid', and can be configured with
4257 `org-agenda-time-grid'.
4260 File: org, Node: Sorting of agenda items, Prev: Time-of-day specifications, Up: Presentation and sorting
4262 9.4.3 Sorting of agenda items
4263 -----------------------------
4265 Before being inserted into a view, the items are sorted. How this is
4266 done depends on the type of view.
4267 * For the daily/weekly agenda, the items for each day are sorted.
4268 The default order is to first collect all items containing an
4269 explicit time-of-day specification. These entries will be shown
4270 at the beginning of the list, as a _schedule_ for the day. After
4271 that, items remain grouped in categories, in the sequence given by
4272 `org-agenda-files'. Within each category, items are sorted by
4273 priority (*note Priorities::), which is composed of the base
4274 priority (2000 for priority `A', 1000 for `B', and 0 for `C'),
4275 plus additional increments for overdue scheduled or deadline items.
4277 * For the TODO list, items remain in the order of categories, but
4278 within each category, sorting takes place according to priority
4279 (*note Priorities::).
4281 * For tags matches, items are not sorted at all, but just appear in
4282 the sequence in which they are found in the agenda files.
4284 Sorting can be customized using the variable
4285 `org-agenda-sorting-strategy'.
4288 File: org, Node: Agenda commands, Next: Custom agenda views, Prev: Presentation and sorting, Up: Agenda views
4290 9.5 Commands in the agenda buffer
4291 =================================
4293 Entries in the agenda buffer are linked back to the org file or diary
4294 file where they originate. You are not allowed to edit the agenda
4295 buffer itself, but commands are provided to show and jump to the
4296 original entry location, and to edit the org-files "remotely" from the
4297 agenda buffer. In this way, all information is stored only once,
4298 removing the risk that your agenda and note files may diverge.
4300 Some commands can be executed with mouse clicks on agenda lines. For
4301 the other commands, the cursor needs to be in the desired line.
4307 Next line (same as <up>).
4310 Previous line (same as <down>).
4317 Display the original location of the item in another window.
4320 Display original location and recenter that window.
4325 Go to the original location of the item in another window. Under
4326 Emacs 22, `mouse-1' will also works for this.
4329 Go to the original location of the item and delete other windows.
4332 Toggle Follow mode. In Follow mode, as you move the cursor through
4333 the agenda buffer, the other window always shows the corresponding
4334 location in the org file. The initial setting for this mode in new
4335 agenda buffers can be set with the variable
4336 `org-agenda-start-with-follow-mode'.
4339 Display the entire subtree of the current item in an indirect
4340 buffer. With numerical prefix ARG, go up to this level and then
4341 take that tree. If ARG is negative, go up that many levels. With
4342 `C-u' prefix, do not remove the previously used indirect buffer.
4345 Toggle Logbook mode. In Logbook mode, entries that where marked
4346 DONE while logging was on (variable `org-log-done') are shown in
4347 the agenda, as are entries that have been clocked on that day.
4353 Delete other windows.
4356 Switch to day/week/month/year view. When switching to day or week
4357 view, this setting becomes the default for subseqent agenda
4358 commands. Since month and year views are slow to create, the do
4359 not become the default.
4362 Toggle the inclusion of diary entries. See *Note Weekly/Daily
4366 Toggle the time grid on and off. See also the variables
4367 `org-agenda-use-time-grid' and `org-agenda-time-grid'.
4370 Recreate the agenda buffer, for example to reflect the changes
4371 after modification of the time stamps of items with S-<left> and
4372 S-<right>. When the buffer is the global todo list, a prefix
4373 argument is interpreted to create a selective list for a specific
4377 Save all Org-mode buffers in the current Emacs session.
4380 Display the following `org-agenda-ndays' days. For example, if
4381 the display covers a week, switch to the following week. With
4382 prefix arg, go forward that many times `org-agenda-ndays' days.
4385 Display the previous dates.
4397 Undo a change due to a remote editing command. The change is
4398 undone both in the agenda buffer and in the remote buffer.
4401 Change the TODO state of the item, both in the agenda and in the
4405 Delete the current agenda item along with the entire subtree
4406 belonging to it in the original Org-mode file. If the text to be
4407 deleted remotely is longer than one line, the kill needs to be
4408 confirmed by the user. See variable `org-agenda-confirm-kill'.
4411 Archive the subtree corresponding to the current headline.
4414 Show all tags associated with the current item. Because of
4415 inheritance, this may be more than the tags listed in the line
4419 Set tags for the current headline.
4422 Toggle the ARCHIVE tag for the current headline.
4425 Set the priority for the current item. Org-mode prompts for the
4426 priority character. If you reply with <SPC>, the priority cookie
4427 is removed from the entry.
4430 Display weighted priority of current item.
4434 Increase the priority of the current item. The priority is
4435 changed in the original buffer, but the agenda is not resorted.
4436 Use the `r' key for this.
4440 Decrease the priority of the current item.
4446 Set a deadline for this item.
4449 Change the time stamp associated with the current line by one day
4450 into the future. With prefix argument, change it by that many
4451 days. For example, `3 6 5 S-<right>' will change it by a year.
4452 The stamp is changed in the original org file, but the change is
4453 not directly reflected in the agenda buffer. Use the `r' key to
4457 Change the time stamp associated with the current line by one day
4461 Change the time stamp associated with the current line to today.
4462 The key `>' has been chosen, because it is the same as `S-.' on my
4466 Start the clock on the current item. If a clock is running
4467 already, it is stopped first.
4470 Stop the previously started clock.
4473 Cancel the currently running clock.
4479 Open the Emacs calendar and move to the date at the agenda cursor.
4482 When in the calendar, compute and show the Org-mode agenda for the
4486 Insert a new entry into the diary. Prompts for the type of entry
4487 (day, weekly, monthly, yearly, anniversary, cyclic) and creates a
4488 new entry in the diary, just as `i d' etc. would do in the
4489 calendar. The date is taken from the cursor position.
4492 Show the phases of the moon for the three months around current
4496 Show sunrise and sunset times. The geographical location must be
4497 set with calendar variables, see documentation of the Emacs
4501 Convert the date at cursor into many other cultural and historic
4505 Show holidays for three month around the cursor date.
4508 Export a single iCalendar file containing entries from all agenda
4515 Write the agenda view to a file. Depending on the extension of the
4516 selected file name, the view will be exported as HTML (extension
4517 `.html' or `.htm'), Postscript (extension `.ps'), or plain text
4518 (any other extension). Use the variable
4519 `org-agenda-exporter-settings' to set options for `ps-print' and
4520 for `htmlize' to be used during export.
4526 Quit agenda, remove the agenda buffer.
4529 Exit agenda, remove the agenda buffer and all buffers loaded by
4530 Emacs for the compilation of the agenda. Buffers created by the
4531 user to visit org files will not be removed.
4534 File: org, Node: Custom agenda views, Prev: Agenda commands, Up: Agenda views
4536 9.6 Custom agenda views
4537 =======================
4539 Custom agenda commands serve two purposes: to store and quickly access
4540 frequently used TODO and tags searches, and to create special composite
4541 agenda buffers. Custom agenda commands will be accessible through the
4542 dispatcher (*note Agenda dispatcher::), just like the default commands.
4546 * Storing searches:: Type once, use often
4547 * Block agenda:: All the stuff you need in a single buffer
4548 * Setting Options:: Changing the rules
4549 * Exporting Agenda Views:: Writing agendas to files.
4550 * Extracting Agenda Information for other programs::
4553 File: org, Node: Storing searches, Next: Block agenda, Prev: Custom agenda views, Up: Custom agenda views
4555 9.6.1 Storing searches
4556 ----------------------
4558 The first application of custom searches is the definition of keyboard
4559 shortcuts for frequently used searches, either creating an agenda
4560 buffer, or a sparse tree (the latter covering of course only the current
4561 buffer). Custom commands are configured in the variable
4562 `org-agenda-custom-commands'. You can customize this variable, for
4563 example by pressing `C-c a C'. You can also directly set it with Emacs
4564 Lisp in `.emacs'. The following example contains all valid search
4567 (setq org-agenda-custom-commands
4568 '(("w" todo "WAITING")
4569 ("W" todo-tree "WAITING")
4570 ("u" tags "+BOSS-URGENT")
4571 ("v" tags-todo "+BOSS-URGENT")
4572 ("U" tags-tree "+BOSS-URGENT")
4573 ("f" occur-tree "\\<FIXME\\>")))
4575 The initial single-character string in each entry defines the character
4576 you have to press after the dispatcher command `C-c a' in order to
4577 access the command. The second parameter is the search type, followed
4578 by the string or regular expression to be used for the matching. The
4579 example above will therefore define:
4582 as a global search for TODO entries with `WAITING' as the TODO
4586 as the same search, but only in the current buffer and displaying
4587 the results as a sparse tree
4590 as a global tags search for headlines marked `:BOSS:' but not
4594 as the same search as `C-c a u', but limiting the search to
4595 headlines that are also TODO items
4598 as the same search as `C-c a u', but only in the current buffer and
4599 displaying the result as a sparse tree
4602 to create a sparse tree (again: current buffer only) with all
4603 entries containing the word `FIXME'.
4606 File: org, Node: Block agenda, Next: Setting Options, Prev: Storing searches, Up: Custom agenda views
4611 Another possibility is the construction of agenda views that comprise
4612 the results of _several_ commands, each of which creates a block in the
4613 agenda buffer. The available commands include `agenda' for the daily
4614 or weekly agenda (as created with `C-c a a'), `alltodo' for the global
4615 todo list (as constructed with `C-c a t'), and the matching commands
4616 discussed above: `todo', `tags', and `tags-todo'. Here are two
4619 (setq org-agenda-custom-commands
4620 '(("h" "Agenda and Home-related tasks"
4624 ("o" "Agenda and Office-related tasks"
4629 This will define `C-c a h' to create a multi-block view for stuff you
4630 need to attend to at home. The resulting agenda buffer will contain
4631 your agenda for the current week, all TODO items that carry the tag
4632 `HOME', and also all lines tagged with `GARDEN'. Finally the command
4633 `C-c a o' provides a similar view for office tasks.
4636 File: org, Node: Setting Options, Next: Exporting Agenda Views, Prev: Block agenda, Up: Custom agenda views
4638 9.6.3 Setting Options for custom commands
4639 -----------------------------------------
4641 Org-mode contains a number of variables regulating agenda construction
4642 and display. The global variables define the behavior for all agenda
4643 commands, including the custom commands. However, if you want to change
4644 some settings just for a single custom view, you can do so. Setting
4645 options requires inserting a list of variable names and values at the
4646 right spot in `org-agenda-custom-commands'. For example:
4648 (setq org-agenda-custom-commands
4649 '(("w" todo "WAITING"
4650 ((org-agenda-sorting-strategy '(priority-down))
4651 (org-agenda-prefix-format " Mixed: ")))
4652 ("U" tags-tree "+BOSS-URGENT"
4653 ((org-show-following-heading nil)
4654 (org-show-hierarchy-above nil)))))
4656 Now the `C-c a w' command will sort the collected entries only by
4657 priority, and the prefix format is modified to just say ` Mixed:'
4658 instead of giving the category of the entry. The sparse tags tree of
4659 `C-c a U' will now turn out ultra-compact, because neither the headline
4660 hierarchy above the match, nor the headline following the match will be
4663 For command sets creating a block agenda,
4664 `org-agenda-custom-commands' has two separate spots for setting
4665 options. You can add options that should be valid for just a single
4666 command in the set, and options that should be valid for all commands in
4667 the set. The former are just added to the command entry, the latter
4668 must come after the list of command entries. Going back to the block
4669 agenda example (*note Block agenda::), let's change the sorting strategy
4670 for the `C-c a h' commands to `priority-down', but let's sort the
4671 results for GARDEN tags query in the opposite order, `priority-up'.
4672 This would look like this:
4674 (setq org-agenda-custom-commands
4675 '(("h" "Agenda and Home-related tasks"
4679 ((org-agenda-sorting-strategy '(priority-up)))))
4680 ((org-agenda-sorting-strategy '(priority-down))))
4681 ("o" "Agenda and Office-related tasks"
4686 As you see, the values and parenthesis setting is a little complex.
4687 When in doubt, use the customize interface to set this variable - it
4688 fully supports its structure. Just one caveat: When setting options in
4689 this interface, the _values_ are just lisp expressions. So if the
4690 value is a string, you need to add the double quotes around the value
4694 File: org, Node: Exporting Agenda Views, Next: Extracting Agenda Information for other programs, Prev: Setting Options, Up: Custom agenda views
4696 9.6.4 Exporting Agenda Views
4697 ----------------------------
4699 If you are away from your computer, it can be very useful to have a
4700 printed version of some agenda views to carry around. Org-mode can
4701 export custom agenda views as plain text, HTML(1) and postscript. If
4702 you want to do this only occasionally, use the commend
4705 Write the agenda view to a file. Depending on the extension of the
4706 selected file name, the view will be exported as HTML (extension
4707 `.html' or `.htm'), Postscript (extension `.ps'), or plain text
4708 (any other extension). Use the variable
4709 `org-agenda-exporter-settings' to set options for `ps-print' and
4710 for `htmlize' to be used during export, for example
4711 (setq org-agenda-exporter-settings
4712 '((ps-number-of-columns 2)
4713 (ps-landscape-mode t)
4714 (htmlize-output-type 'css)))
4716 If you need to export certain agenda views frequently, you can
4717 associate any custom agenda command with a list of output file names
4718 (2). Here is an example that first does define custom commands for the
4719 agenda and the global todo list, together with a number of files to
4720 which to export them. Then we define two block agenda commands and
4721 specify filenames for them as well. File names can be relative to the
4722 current working directory, or absolute.
4724 (setq org-agenda-custom-commands
4725 '(("X" agenda "" nil ("agenda.html" "agenda.ps"))
4726 ("Y" alltodo "" nil ("todo.html" "todo.txt" "todo.ps"))
4727 ("h" "Agenda and Home-related tasks"
4732 ("~/views/home.html"))
4733 ("o" "Agenda and Office-related tasks"
4738 ("~/views/office.ps"))))
4740 The extension of the file name determines the type of export. If it
4741 is `.html', Org-mode will use the `htmlize.el' package to convert the
4742 buffer to HTML and save it to this file name. If the extension is
4743 `.ps', `ps-print-buffer-with-faces' is used to produce postscript
4744 output. Any other extension produces a plain ASCII file.
4746 The export files are _not_ created when you use one of those
4747 commands interactively. Instead, there is a special command to produce
4748 _all_ specified files in one step:
4751 Export all agenda views that have export filenames associated with
4754 You can use the options section of the custom agenda commands to also
4755 set options for the export commands. For example:
4757 (setq org-agenda-custom-commands
4759 ((ps-number-of-columns 2)
4760 (ps-landscape-mode t)
4761 (org-agenda-prefix-format " [ ] ")
4762 (org-agenda-with-colors nil)
4763 (org-agenda-remove-tags t))
4766 This command sets two options for the postscript exporter, to make it
4767 print in two columns in landscape format - the resulting page can be cut
4768 in two and then used in a paper agenda. The remaining settings modify
4769 the agenda prefix to omit category and scheduling information, and
4770 instead include a checkbox to check off items. We also remove the tags
4771 to make the lines compact, and we don't want to use colors for the
4772 black-and-white printer. Settings specified in
4773 `org-agenda-exporter-settings' will also apply, but the settings in
4774 `org-agenda-custom-commands' take precedence.
4776 From the command line you may also use
4777 emacs -f org-batch-store-agenda-views -kill
4778 or, if you need to modify some parameters
4779 emacs -eval '(org-batch-store-agenda-views \
4780 org-agenda-ndays 30 \
4781 org-agenda-include-diary nil \
4782 org-agenda-files (quote ("~/org/project.org")))' \
4784 which will create the agenda views restricted to the file
4785 `~/org/project.org', without diary entries and with 30 days extent.
4787 ---------- Footnotes ----------
4789 (1) You need to install Hrvoje Niksic' `htmlize.el'.
4791 (2) If you want to store standard views like the weekly agenda or
4792 the global TODO list as well, you need to define custom commands for
4793 them in order to be able to specify filenames.
4796 File: org, Node: Extracting Agenda Information for other programs, Prev: Exporting Agenda Views, Up: Custom agenda views
4798 9.6.5 Extracting Agenda Information for other programs
4799 ------------------------------------------------------
4801 Org-mode provides commands to access agenda information for the command
4802 line in emacs batch mode. This extracted information can be sent
4803 directly to a printer, or it can be read by a program that does further
4804 processing of the data. The first of these commands is the function
4805 `org-batch-agenda', that produces an agenda view and sends it as ASCII
4806 text to STDOUT. The command takes a single string as parameter. If
4807 the string has length 1, it is used as a key to one of the commands you
4808 have configured in `org-agenda-custom-commands', basically any key you
4809 can use after `C-c a'. For example, to directly print the current TODO
4812 emacs -batch -l ~/.emacs -eval '(org-batch-agenda "t")' | lpr
4814 If the parameter is a string with 2 or more characters, it is used
4815 as a tags/todo match string. For example, to print your local shopping
4816 list (all items with the tag `shop', but excluding the tag `NewYork'),
4819 emacs -batch -l ~/.emacs \
4820 -eval '(org-batch-agenda "+shop-NewYork")' | lpr
4822 You may also modify parameters on the fly like this:
4824 emacs -batch -l ~/.emacs \
4825 -eval '(org-batch-agenda "a" \
4826 org-agenda-ndays 30 \
4827 org-agenda-include-diary nil \
4828 org-agenda-files (quote ("~/org/project.org")))' \
4831 which will produce a 30 day agenda, fully restricted to the Org file
4832 `~/org/projects.org', not even including the diary.
4834 If you want to process the agenda data in more sophisticated ways,
4835 you can use the command `org-batch-agenda-csv' to get a comma-separated
4836 list of values for each agenda item. Each line in the output will
4837 contain a number of fields separated by commas. The fields in a line
4840 category The category of the item
4841 head The headline, without TODO kwd, TAGS and PRIORITY
4842 type The type of the agenda entry, can be
4843 todo selected in TODO match
4844 tagsmatch selected in tags match
4845 diary imported from diary
4848 timestamp appointment, selected by timestamp
4849 closed entry was closed on date
4850 upcoming-deadline warning about nearing deadline
4851 past-scheduled forwarded scheduled item
4852 block entry has date block including date
4853 todo The todo keyword, if any
4854 tags All tags including inherited ones, separated by colons
4855 date The relevant date, like 2007-2-14
4856 time The time, like 15:00-16:50
4857 extra String with extra planning info
4858 priority-l The priority letter if any was given
4859 priority-n The computed numerical priority
4861 Time and date will only be given if a timestamp (or deadline/scheduled)
4862 lead to the selection of the item.
4864 A CSV list like this is very easy to use in a post processing script.
4865 For example, here is a Perl program that gets the TODO list from
4866 Emacs/org-mode and prints all the items, preceded by a checkbox:
4870 # define the Emacs command to run
4871 $cmd = "emacs -batch -l ~/.emacs -eval '(org-batch-agenda-csv \"t\")'";
4873 # run it and capture the output
4874 $agenda = qx{$cmd 2>/dev/null};
4876 # loop over all lines
4877 foreach $line (split(/\n/,$agenda)) {
4879 # get the individual values
4880 ($category,$head,$type,$todo,$tags,$date,$time,$extra,
4881 $priority_l,$priority_n) = split(/,/,$line);
4883 # proccess and print
4884 print "[ ] $head\n";
4888 File: org, Node: Embedded LaTeX, Next: Exporting, Prev: Agenda views, Up: Top
4893 Plain ASCII is normally sufficient for almost all note taking. One
4894 exception, however, are scientific notes which need to be able to
4895 contain mathematical symbols and the occasional formula. LaTeX(1) is
4896 widely used to typeset scientific documents. Org-mode supports
4897 embedding LaTeX code into its files, because many academics are used to
4898 read LaTeX source code, and because it can be readily processed into
4899 images for HTML production.
4901 It is not necessary to mark LaTeX macros and code in any special way.
4902 If you observe a few conventions, Org-mode knows how to find it and what
4907 * Math symbols:: TeX macros for symbols and Greek letters
4908 * Subscripts and Superscripts:: Simple syntax for raising/lowering text
4909 * LaTeX fragments:: Complex formulas made easy
4910 * Processing LaTeX fragments:: Previewing LaTeX processing
4911 * CDLaTeX mode:: Speed up entering of formulas
4913 ---------- Footnotes ----------
4915 (1) LaTeX is a macro system based on Donald E. Knuth's TeX system.
4916 Many of the features described here as "LaTeX" are really from TeX, but
4917 for simplicity I am blurring this distinction.
4920 File: org, Node: Math symbols, Next: Subscripts and Superscripts, Prev: Embedded LaTeX, Up: Embedded LaTeX
4925 You can use LaTeX macros to insert special symbols like `\alpha' to
4926 indicate the Greek letter, or `\to' to indicate an arrow. Completion
4927 for these macros is available, just type `\' and maybe a few letters,
4928 and press `M-<TAB>' to see possible completions. Unlike LaTeX code,
4929 Org-mode allows these macros to be present without surrounding math
4930 delimiters, for example:
4932 Angles are written as Greek letters \alpha, \beta and \gamma.
4934 During HTML export (*note HTML export::), these symbols are
4935 translated into the proper syntax for HTML, for the above examples this
4936 is `α' and `→', respectively.
4939 File: org, Node: Subscripts and Superscripts, Next: LaTeX fragments, Prev: Math symbols, Up: Embedded LaTeX
4941 10.2 Subscripts and Superscripts
4942 ================================
4944 Just like in LaTeX, `^' and `_' are used to indicate super- and
4945 subscripts. Again, these can be used without embedding them in
4946 math-mode delimiters. To increase the readability of ASCII text, it is
4947 not necessary (but OK) to surround multi-character sub- and superscripts
4948 with curly braces. For example
4950 The mass if the sun is M_sun = 1.989 x 10^30 kg. The radius of
4951 the sun is R_{sun} = 6.96 x 10^8 m.
4953 To avoid interpretation as raised or lowered text, you can quote `^'
4954 and `_' with a backslash: `\_' and `\^'.
4956 During HTML export (*note HTML export::), subscript and superscripts
4957 are surrounded with `<sub>' and `<sup>' tags, respectively.
4960 File: org, Node: LaTeX fragments, Next: Processing LaTeX fragments, Prev: Subscripts and Superscripts, Up: Embedded LaTeX
4962 10.3 LaTeX fragments
4963 ====================
4965 With symbols, sub- and superscripts, HTML is pretty much at its end when
4966 it comes to representing mathematical formulas(1). More complex
4967 expressions need a dedicated formula processor. To this end, Org-mode
4968 can contain arbitrary LaTeX fragments. It provides commands to preview
4969 the typeset result of these fragments, and upon export to HTML, all
4970 fragments will be converted to images and inlined into the HTML
4971 document. For this to work you need to be on a system with a working
4972 LaTeX installation. You also need the `dvipng' program, available at
4973 `http://sourceforge.net/projects/dvipng/'. The LaTeX header that will
4974 be used when processing a fragment can be configured with the variable
4975 `org-format-latex-header'.
4977 LaTeX fragments don't need any special marking at all. The following
4978 snippets will be identified as LaTeX source code:
4979 * Environments of any kind. The only requirement is that the
4980 `\begin' statement appears on a new line, preceded by only
4983 * Text within the usual LaTeX math delimiters. To avoid conflicts
4984 with currency specifications, single `$' characters are only
4985 recognized as math delimiters if the enclosed text contains at
4986 most two line breaks, is directly attached to the `$' characters
4987 with no whitespace in between, and if the closing `$' is followed
4988 by whitespace or punctuation. For the other delimiters, there is
4989 no such restriction, so when in doubt, use `\(...\)' as inline
4994 \begin{equation} % arbitrary environments,
4995 x=\sqrt{b} % even tables, figures
4996 \end{equation} % etc
4998 If $a^2=b$ and \( b=2 \), then the solution must be
4999 either $$ a=+\sqrt{2} $$ or \[ a=-\sqrt{2} \].
5001 If you need any of the delimiter ASCII sequences for other purposes, you
5002 can configure the option `org-format-latex-options' to deselect the
5003 ones you do not wish to have interpreted by the LaTeX converter.
5005 ---------- Footnotes ----------
5007 (1) Yes, there is MathML, but that is not yet fully supported by
5008 many browsers, and there is no decent converter for turning LaTeX of
5009 ASCII representations of formulas into MathML. So for the time being,
5010 converting formulas into images seems the way to go.
5013 File: org, Node: Processing LaTeX fragments, Next: CDLaTeX mode, Prev: LaTeX fragments, Up: Embedded LaTeX
5015 10.4 Processing LaTeX fragments
5016 ===============================
5018 LaTeX fragments can be processed to produce a preview images of the
5019 typeset expressions:
5022 Produce a preview image of the LaTeX fragment at point and overlay
5023 it over the source code. If there is no fragment at point,
5024 process all fragments in the current entry (between two
5025 headlines). When called with a prefix argument, process the
5026 entire subtree. When called with two prefix arguments, or when
5027 the cursor is before the first headline, process the entire buffer.
5030 Remove the overlay preview images.
5032 During HTML export (*note HTML export::), all LaTeX fragments are
5033 converted into images and inlined into the document if the following
5036 (setq org-export-with-LaTeX-fragments t)
5039 File: org, Node: CDLaTeX mode, Prev: Processing LaTeX fragments, Up: Embedded LaTeX
5041 10.5 Using CDLaTeX to enter math
5042 ================================
5044 CDLaTeX-mode is a minor mode that is normally used in combination with a
5045 major LaTeX mode like AUCTeX in order to speed-up insertion of
5046 environments and math templates. Inside Org-mode, you can make use of
5047 some of the features of cdlatex-mode. You need to install `cdlatex.el'
5048 and `texmathp.el' (the latter comes also with AUCTeX) from
5049 `http://www.astro.uva.nl/~dominik/Tools/cdlatex'. Don't turn
5050 cdlatex-mode itself under Org-mode, but use the light version
5051 `org-cdlatex-mode' that comes as part of Org-mode. Turn it on for the
5052 current buffer with `M-x org-cdlatex-mode', or for all Org-mode files
5055 (add-hook 'org-mode-hook 'turn-on-org-cdlatex)
5057 When this mode is enabled, the following features are present (for
5058 more details see the documentation of cdlatex-mode):
5059 * Environment templates can be inserted with `C-c {'.
5061 * The <TAB> key will do template expansion if the cursor is inside a
5062 LaTeX fragment(1). For example, <TAB> will expand `fr' to
5063 `\frac{}{}' and position the cursor correctly inside the first
5064 brace. Another <TAB> will get you into the second brace. Even
5065 outside fragments, <TAB> will expand environment abbreviations at
5066 the beginning of a line. For example, if you write `equ' at the
5067 beginning of a line and press <TAB>, this abbreviation will be
5068 expanded to an `equation' environment. To get a list of all
5069 abbreviations, type `M-x cdlatex-command-help'.
5071 * Pressing `_' and `^' inside a LaTeX fragment will insert these
5072 characters together with a pair of braces. If you use <TAB> to
5073 move out of the braces, and if the braces surround only a single
5074 character or macro, they are removed again (depending on the
5075 variable `cdlatex-simplify-sub-super-scripts').
5077 * Pressing the backquote ``' followed by a character inserts math
5078 macros, also outside LaTeX fragments. If you wait more than 1.5
5079 seconds after the backquote, a help window will pop up.
5081 * Pressing the normal quote `'' followed by another character
5082 modifies the symbol before point with an accent or a font. If you
5083 wait more than 1.5 seconds after the backquote, a help window will
5084 pop up. Character modification will work only inside LaTeX
5085 fragments, outside the quote is normal.
5087 ---------- Footnotes ----------
5089 (1) Org-mode has a method to test if the cursor is inside such a
5090 fragment, see the documentation of the function
5091 `org-inside-LaTeX-fragment-p'.
5094 File: org, Node: Exporting, Next: Publishing, Prev: Embedded LaTeX, Up: Top
5099 Org-mode documents can be exported into a variety of other formats. For
5100 printing and sharing of notes, ASCII export produces a readable and
5101 simple version of an Org-mode file. HTML export allows you to publish a
5102 notes file on the web, while the XOXO format provides a solid base for
5103 exchange with a broad range of other applications. To incorporate
5104 entries with associated times like deadlines or appointments into a
5105 desktop calendar program like iCal, Org-mode can also produce extracts
5106 in the iCalendar format. Currently Org-mode only supports export, not
5107 import of these different formats.
5109 When exporting, Org-mode uses special conventions to enrich the
5110 output produced. *Note Text interpretation::, for more details.
5113 Dispatcher for export and publishing commands. Displays a
5114 help-window listing the additional key(s) needed to launch an
5115 export or publishing command.
5119 * ASCII export:: Exporting to plain ASCII
5120 * HTML export:: Exporting to HTML
5121 * XOXO export:: Exporting to XOXO
5122 * iCalendar export:: Exporting in iCalendar format
5123 * Text interpretation:: How the exporter looks at the file
5126 File: org, Node: ASCII export, Next: HTML export, Prev: Exporting, Up: Exporting
5131 ASCII export produces a simple and very readable version of an Org-mode
5135 Export as ASCII file. If there is an active region, only the
5136 region will be exported. For an org file `myfile.org', the ASCII
5137 file will be `myfile.txt'. The file will be overwritten without
5141 Export only the visible part of the document.
5143 In the exported version, the first 3 outline levels will become
5144 headlines, defining a general document structure. Additional levels
5145 will be exported as itemized lists. If you want that transition to
5146 occur at a different level, specify it with a prefix argument. For
5151 creates only top level headlines and does the rest as items. When
5152 headlines are converted to items, the indentation of the text following
5153 the headline is changed to fit nicely under the item. This is done with
5154 the assumption that the first bodyline indicates the base indentation of
5155 the body text. Any indentation larger than this is adjusted to preserve
5156 the layout relative to the first line. Should there be lines with less
5157 indentation than the first, these are left alone.
5160 File: org, Node: HTML export, Next: XOXO export, Prev: ASCII export, Up: Exporting
5165 Org-mode contains an HTML (XHTML 1.0 strict) exporter with extensive
5166 HTML formatting, in ways similar to John Grubers _markdown_ language,
5167 but with additional support for tables.
5171 * Export commands:: How to invoke HTML export
5172 * Quoting HTML tags:: Using direct HTML in Org-mode
5173 * Links:: How hyperlinks get transferred to HTML
5174 * Images:: To inline or not to inline?
5175 * CSS support:: Style specifications
5178 File: org, Node: Export commands, Next: Quoting HTML tags, Prev: HTML export, Up: HTML export
5180 11.2.1 HTML export commands
5181 ---------------------------
5184 Export as HTML file `myfile.html'.
5187 Export as HTML file and open it with a browser.
5190 Export to a temporary buffer, do not create a file.
5193 Export the active region to a temporary buffer. With prefix arg,
5194 do not produce file header and foot, but just the plain HTML
5195 section for the region. This is good for cut-and-paste operations.
5204 Export only the visible part of the document.
5206 `M-x org-export-region-as-html'
5207 Convert the region to HTML under the assumption that it was
5208 org-mode syntax before. This is a global command that can be
5209 invoked in any buffer.
5211 In the exported version, the first 3 outline levels will become
5212 headlines, defining a general document structure. Additional levels
5213 will be exported as itemized lists. If you want that transition to
5214 occur at a different level, specify it with a prefix argument. For
5219 creates two levels of headings and does the rest as items.
5222 File: org, Node: Quoting HTML tags, Next: Links, Prev: Export commands, Up: HTML export
5224 11.2.2 Quoting HTML tags
5225 ------------------------
5227 Plain `<' and `>' are always transformed to `<' and `>' in HTML
5228 export. If you want to include simple HTML tags which should be
5229 interpreted as such, mark them with `@' as in `@<b>bold text@</b>'.
5230 Note that this really works only for simple tags. For more extensive
5231 HTML that should be copied verbatim to the exported file use either
5233 #+HTML: Literal HTML code for export
5238 All lines between these markers are exported literally
5242 File: org, Node: Links, Next: Images, Prev: Quoting HTML tags, Up: HTML export
5247 Internal links (*note Internal links::) will continue to work in HTML
5248 files only if they match a dedicated `<<target>>'. Automatic links
5249 created by radio targets (*note Radio targets::) will also work in the
5250 HTML file. Links to external files will still work if the HTML file is
5251 in the same directory as the Org-mode file. Links to other `.org'
5252 files will be translated into HTML links under the assumption that an
5253 HTML version also exists of the linked file. For information related to
5254 linking files while publishing them to a publishing directory see *Note
5258 File: org, Node: Images, Next: CSS support, Prev: Links, Up: HTML export
5263 HTML export can inline images given as links in the Org-mode file, and
5264 it can make an image the clickable part of a link. By default(1),
5265 images are inlined if a link does not have a description. So
5266 `[[file:myimg.jpg]]' will be inlined, while `[[file:myimg.jpg][the
5267 image]]' will just produce a link `the image' that points to the image.
5268 If the description part itself is a `file:' link or a `http:' URL
5269 pointing to an image, this image will be inlined and activated so that
5270 clicking on the image will activate the link. For example, to include
5271 a thumbnail that will link to a high resolution version of the image,
5274 [[file:highres.jpg][file:thumb.jpg]]
5276 and you could use `http' addresses just as well.
5278 ---------- Footnotes ----------
5280 (1) but see the variable `org-export-html-inline-images'
5283 File: org, Node: CSS support, Prev: Images, Up: HTML export
5288 You can also give style information for the exported file. The HTML
5289 exporter assigns the following CSS classes to appropriate parts of the
5290 document - your style specifications may change these:
5292 .done the DONE keyword
5293 .timestamp time stamp
5294 .timestamp-kwd keyword associated with a time stamp, like SCHEDULED
5295 .tag tag in a headline
5296 .target target for links
5298 The default style specification can be configured through the option
5299 `org-export-html-style'. If you want to use a file-local style, you
5300 may use file variables, best wrapped into a COMMENT section at the end
5301 of the outline tree. For example(1):
5303 * COMMENT html style specifications
5306 # org-export-html-style: " <style type=\"text/css\">
5307 # p {font-weight: normal; color: gray; }
5308 # h1 {color: black; }
5312 Remember to execute `M-x normal-mode' after changing this to make
5313 the new style visible to Emacs. This command restarts org-mode for the
5314 current buffer and forces Emacs to re-evaluate the local variables
5315 section in the buffer.
5317 ---------- Footnotes ----------
5319 (1) Under Emacs 21, the continuation lines for a variable value
5320 should have no `#' at the start of the line.
5323 File: org, Node: XOXO export, Next: iCalendar export, Prev: HTML export, Up: Exporting
5328 Org-mode contains an exporter that produces XOXO-style output.
5329 Currently, this exporter only handles the general outline structure and
5330 does not interpret any additional Org-mode features.
5333 Export as XOXO file `myfile.html'.
5336 Export only the visible part of the document.
5339 File: org, Node: iCalendar export, Next: Text interpretation, Prev: XOXO export, Up: Exporting
5341 11.4 iCalendar export
5342 =====================
5344 Some people like to use Org-mode for keeping track of projects, but
5345 still prefer a standard calendar application for anniversaries and
5346 appointments. In this case it can be useful to have deadlines and
5347 other time-stamped items in Org-mode files show up in the calendar
5348 application. Org-mode can export calendar information in the standard
5349 iCalendar format. If you also want to have TODO entries included in the
5350 export, configure the variable `org-icalendar-include-todo'.
5353 Create iCalendar entries for the current file and store them in
5354 the same directory, using a file extension `.ics'.
5357 Like `C-c C-e i', but do this for all files in `org-agenda-files'.
5358 For each of these files, a separate iCalendar file will be
5362 Create a single large iCalendar file from all files in
5363 `org-agenda-files' and write it to the file given by
5364 `org-combined-agenda-icalendar-file'.
5366 How this calendar is best read and updated, depends on the
5367 application you are using. The FAQ covers this issue.
5370 File: org, Node: Text interpretation, Prev: iCalendar export, Up: Exporting
5372 11.5 Text interpretation by the exporter
5373 ========================================
5375 The exporter backends interpret additional structure in the Org-mode
5376 file in order to produce better output.
5380 * Comment lines:: Some lines will not be exported
5381 * Initial text:: Text before the first headline
5382 * Footnotes:: Numbers like [1]
5383 * Enhancing text:: Subscripts, symbols and more
5384 * Export options:: How to influence the export settings
5387 File: org, Node: Comment lines, Next: Initial text, Prev: Text interpretation, Up: Text interpretation
5389 11.5.1 Comment lines
5390 --------------------
5392 Lines starting with `#' in column zero are treated as comments and will
5393 never be exported. Also entire subtrees starting with the word
5394 `COMMENT' will never be exported.
5397 Toggle the COMMENT keyword at the beginning of an entry.
5400 File: org, Node: Initial text, Next: Footnotes, Prev: Comment lines, Up: Text interpretation
5402 11.5.2 Text before the first headline
5403 -------------------------------------
5405 Org-mode normally ignores any text before the first headline when
5406 exporting, leaving this region for internal links to speed up navigation
5407 etc. However, in publishing-oriented files, you might want to have some
5408 text before the first headline, like a small introduction, special HTML
5409 code with a navigation bar, etc. You can ask to have this part of the
5410 file exported as well by setting the variable
5411 `org-export-skip-text-before-1st-heading' to `nil'. On a per-file
5412 basis, you can get the same effect with
5416 The text before the first headline will be fully processed (*note
5417 Enhancing text::), and the first non-comment line becomes the title of
5418 the exported document. If you need to include literal HTML, use the
5419 special constructs described in *Note Quoting HTML tags::. The table
5420 of contents is normally inserted directly before the first headline of
5421 the file. If you would like to get it to a different location, insert
5422 the string `[TABLE-OF-CONTENTS]' on a line by itself at the desired
5425 Finally, if you want to use the space before the first headline for
5426 internal purposes, but _still_ want to place something before the first
5427 headline when exporting the file, you can use the `#+TEXT' construct:
5430 #+TEXT: This text will go before the *first* headline.
5431 #+TEXT: We place the table of contents here:
5432 #+TEXT: [TABLE-OF-CONTENTS]
5433 #+TEXT: This goes between the table of contents and the first headline
5436 File: org, Node: Footnotes, Next: Enhancing text, Prev: Initial text, Up: Text interpretation
5441 Numbers in square brackets are treated as footnotes, so that you can use
5442 the Emacs package `footnote.el' to create footnotes. For example:
5444 The org-mode homepage[1] clearly needs help from
5445 a good web designer.
5447 [1] The link is: http://www.astro.uva.nl/~dominik/Tools/org
5449 Note that the `footnote' package uses `C-c !' to invoke its commands.
5450 This binding conflicts with the org-mode command for inserting inactive
5451 time stamps. You could use the variable `footnote-prefix' to switch
5452 footnotes commands to another key. Or, if you are too used to this
5453 binding, you could use `org-replace-disputed-keys' and
5454 `org-disputed-keys' to change the settings in Org-mode.
5457 File: org, Node: Enhancing text, Next: Export options, Prev: Footnotes, Up: Text interpretation
5459 11.5.4 Enhancing text for export
5460 --------------------------------
5462 Some of the export backends of Org-mode allow for sophisticated text
5463 formatting, this is true in particular for the HTML backend. Org-mode
5464 has a number of typing conventions that allow to produce a richly
5467 * Plain lists `-', `*' or `+' as bullet, or with `1.' or `2)' as
5468 enumerator will be recognized and transformed if the backend
5469 supports lists. See *Note Plain lists::.
5471 * You can make words *bold*, /italic/, _underlined_, `=code=', and
5472 even `+strikethrough+'(1).
5474 * A line consisting of only dashes, and at least 5 of them, will be
5475 exported as a horizontal line (`<hr/>' in HTML).
5477 * Many TeX macros and entire LaTeX fragments are converted into HTML
5478 entities or images (*note Embedded LaTeX::).
5480 * Tables are transformed into native tables under the exporter, if
5481 the export backend supports this. Data fields before the first
5482 horizontal separator line will be formatted as table header fields.
5484 * If a headline starts with the word `QUOTE', the text below the
5485 headline will be typeset as fixed-width, to allow quoting of
5486 computer codes etc. Lines starting with `:' are also typeset in
5489 Toggle fixed-width for entry (QUOTE) or region, see below.
5491 * A double backslash _at the end of a line_ enforces a line break at
5494 If these conversions conflict with your habits of typing ASCII text,
5495 they can all be turned off with corresponding variables. See the
5496 customization group `org-export-general', and the following section
5497 which explains how to set export options with special lines in a buffer.
5499 ---------- Footnotes ----------
5501 (1) but remember that strikethrough is typographically evil and
5502 should never be used.
5505 File: org, Node: Export options, Prev: Enhancing text, Up: Text interpretation
5507 11.5.5 Export options
5508 ---------------------
5510 The exporter recognizes special lines in the buffer which provide
5511 additional information. These lines may be put anywhere in the file.
5512 The whole set of lines can be inserted into the buffer with `C-c C-e
5513 t'. For individual lines, a good way to make sure the keyword is
5514 correct is to type `#+' and then use `M-<TAB>' completion (*note
5518 Insert template with export options, see example below.
5520 #+TITLE: the title to be shown (default is the buffer name)
5521 #+AUTHOR: the author (default taken from `user-full-name')
5522 #+EMAIL: his/her email address (default from `user-mail-address')
5523 #+LANGUAGE: language for HTML, e.g. `en' (`org-export-default-language')
5524 #+TEXT: Some descriptive text to be inserted at the beginning.
5525 #+TEXT: Several lines may be given.
5526 #+OPTIONS: H:2 num:t toc:t \n:nil @:t ::t |:t ^:t f:t *:nil TeX:t LaTeX:t skip:t
5528 The OPTIONS line is a compact form to specify export settings. Here
5530 H: set the number of headline levels for export
5531 num: turn on/off section-numbers
5532 toc: turn on/off table of contents, or set level limit (integer)
5533 \n: turn on/off linebreak-preservation
5534 @: turn on/off quoted HTML tags
5535 :: turn on/off fixed-width sections
5536 |: turn on/off tables
5537 ^: turn on/off TeX-like syntax for sub- and superscripts. If
5538 you write "^:{}", `a_{b}' will be interpreted, but
5539 the simple `a_b' will be left as it is.
5540 f: turn on/off foototes like this[1].
5541 *: turn on/off emphasized text (bold, italic, underlined)
5542 TeX: turn on/off simple TeX macros in plain text
5543 LaTeX: turn on/off LaTeX fragments
5544 skip: turn on/off skipping the text before the first heading
5547 File: org, Node: Publishing, Next: Miscellaneous, Prev: Exporting, Up: Top
5552 Org-mode includes(1) a publishing management system that allows you to
5553 configure automatic HTML conversion of _projects_ composed of
5554 interlinked org files. This system is called _org-publish_. You can
5555 also configure org-publish to automatically upload your exported HTML
5556 pages and related attachments, such as images and source code files, to
5557 a web server. Org-publish turns org-mode into a web-site authoring
5560 Org-publish has been contributed to Org-mode by David O'Toole.
5564 * Configuration:: Defining projects
5565 * Sample configuration:: Example projects
5566 * Triggering publication:: Publication commands
5568 ---------- Footnotes ----------
5570 (1) `org-publish.el' is not distributed with Emacs 21, if you are
5571 still using Emacs 21, you need you need to download this file
5575 File: org, Node: Configuration, Next: Sample configuration, Prev: Publishing, Up: Publishing
5580 Publishing needs significant configuration to specify files, destination
5581 and many other properties of a project.
5585 * Project alist:: The central configuration variable
5586 * Sources and destinations:: From here to there
5587 * Selecting files:: What files are part of the project?
5588 * Publishing action:: Setting the function doing the publishing
5589 * Publishing options:: Tweaking HTML export
5590 * Publishing links:: Which links keep working after publishing?
5591 * Project page index:: Publishing a list of project files
5594 File: org, Node: Project alist, Next: Sources and destinations, Prev: Configuration, Up: Configuration
5596 12.1.1 The variable `org-publish-project-alist'
5597 -----------------------------------------------
5599 Org-publish is configured almost entirely through setting the value of
5600 one variable, called `org-publish-project-alist'. Each element of the
5601 list configures one project, and may be in one of the two following
5604 ("project-name" :property value :property value ...)
5608 ("project-name" :components ("project-name" "project-name" ...))
5610 In both cases, projects are configured by specifying property values.
5611 A project defines the set of files that will be published, as well as
5612 the publishing configuration to use when publishing those files. When
5613 a project takes the second form listed above, the individual members of
5614 the "components" property are taken to be components of the project,
5615 which group together files requiring different publishing options. When
5616 you publish such a "meta-project" all the components will also publish.
5619 File: org, Node: Sources and destinations, Next: Selecting files, Prev: Project alist, Up: Configuration
5621 12.1.2 Sources and destinations for files
5622 -----------------------------------------
5624 Most properties are optional, but some should always be set. In
5625 particular, org-publish needs to know where to look for source files,
5626 and where to put published files.
5628 `:base-directory' Directory containing publishing source files
5629 `:publishing-directory'Directory (possibly remote) where output files
5631 `:preparation-function'Function called before starting publishing
5632 process, for example to run `make' for updating
5633 files to be published.
5636 File: org, Node: Selecting files, Next: Publishing action, Prev: Sources and destinations, Up: Configuration
5638 12.1.3 Selecting files
5639 ----------------------
5641 By default, all files with extension `.org' in the base directory are
5642 considered part of the project. This can be modified by setting the
5644 `:base-extension' Extension (without the dot!) of source files. This
5645 actually is a regular expression.
5646 `:exclude' Regular expression to match file names that should
5647 not be published, even though they have been selected
5648 on the basis of their extension.
5649 `:include' List of files to be included regardless of
5650 `:base-extension' and `:exclude'.
5653 File: org, Node: Publishing action, Next: Publishing options, Prev: Selecting files, Up: Configuration
5655 12.1.4 Publishing Action
5656 ------------------------
5658 Publishing means that a file is copied to the destination directory and
5659 possibly transformed in the process. The default transformation is to
5660 export Org-mode files as HTML files, and this is done by the function
5661 `org-publish-org-to-html' which calls the HTML exporter (*note HTML
5662 export::). Other files like images only need to be copied to the
5663 publishing destination. For non-Org-mode files, you need to specify
5664 the publishing function.
5666 `:publishing-function' Function executing the publication of a file.
5667 This may also be a list of functions, which will
5668 all be called in turn.
5670 The function must accept two arguments: a property list containing at
5671 least a `:publishing-directory' property, and the name of the file to
5672 be published. It should take the specified file, make the necessary
5673 transformation (if any) and place the result into the destination
5674 folder. You can write your own publishing function, but `org-publish'
5675 provides one for attachments (files that only need to be copied):
5676 `org-publish-attachment'.
5679 File: org, Node: Publishing options, Next: Publishing links, Prev: Publishing action, Up: Configuration
5681 12.1.5 Options for the HTML exporter
5682 ------------------------------------
5684 The property list can be used to set many export options for the HTML
5685 exporter. In most cases, these properties correspond to user variables
5686 in Org-mode. The table below lists these properties along with the
5687 variable they belong to. See the documentation string for the
5688 respective variable for details.
5690 `:language' `org-export-default-language'
5691 `:headline-levels' `org-export-headline-levels'
5692 `:section-numbers' `org-export-with-section-numbers'
5693 `:table-of-contents' `org-export-with-toc'
5694 `:archived-trees' `org-export-with-archived-trees'
5695 `:emphasize' `org-export-with-emphasize'
5696 `:sub-superscript' `org-export-with-sub-superscripts'
5697 `:TeX-macros' `org-export-with-TeX-macros'
5698 `:LaTeX-fragments' `org-export-with-LaTeX-fragments'
5699 `:fixed-width' `org-export-with-fixed-width'
5700 `:timestamps' `org-export-with-timestamps'
5702 `:tags' `org-export-with-tags'
5704 `:tables' `org-export-with-tables'
5705 `:table-auto-headline' `org-export-highlight-first-table-line'
5706 `:style' `org-export-html-style'
5707 `:convert-org-links' `org-export-html-link-org-files-as-html'
5708 `:inline-images' `org-export-html-inline-images'
5709 `:expand-quoted-html' `org-export-html-expand'
5710 `:timestamp' `org-export-html-with-timestamp'
5711 `:publishing-directory'`org-export-publishing-directory'
5712 `:preamble' `org-export-html-preamble'
5713 `:postamble' `org-export-html-postamble'
5714 `:auto-preamble' `org-export-html-auto-preamble'
5715 `:auto-postamble' `org-export-html-auto-postamble'
5716 `:author' `user-full-name'
5717 `:email' `user-mail-address'
5719 When a property is given a value in org-publish-project-alist, its
5720 setting overrides the value of the corresponding user variable (if any)
5721 during publishing. Options set within a file (*note Export options::),
5722 however, override everything.
5725 File: org, Node: Publishing links, Next: Project page index, Prev: Publishing options, Up: Configuration
5727 12.1.6 Links between published files
5728 ------------------------------------
5730 To create a link from one Org-mode file to another, you would use
5731 something like `[[file:foo.org][The foo]]' or simply `file:foo.org.'
5732 (*note Hyperlinks::). Upon publishing this link becomes a link to
5733 `foo.html'. In this way, you can interlink the pages of your "org web"
5734 project and the links will work as expected when you publish them to
5737 You may also link to related files, such as images. Provided you are
5738 careful with relative pathnames, and provided you have also configured
5739 org-publish to upload the related files, these links will work too.
5740 *Note Complex example:: for an example of this usage.
5742 Sometime an Org-mode file to be published may contain links that are
5743 only valid in your production environment, but not in the publishing
5744 location. In this case, use the property
5746 `:link-validation-function' Function to validate links
5748 to define a function for checking link validity. This function must
5749 accept two arguments, the file name and a directory relative to which
5750 the file name is interpreted in the production environment. If this
5751 function returns `nil', then the HTML generator will only insert a
5752 description into the HTML file, but no link. One option for this
5753 function is `org-publish-validate-link' which checks if the given file
5754 is part of any project in `org-publish-project-alist'.
5757 File: org, Node: Project page index, Prev: Publishing links, Up: Configuration
5759 12.1.7 Project page index
5760 -------------------------
5762 The following properties may be used to control publishing of an index
5763 of files or summary page for a given project.
5765 `:auto-index' When non-nil, publish an index during
5766 org-publish-current-project or org-publish-all.
5767 `:index-filename' Filename for output of index. Defaults to `index.org'
5768 (which becomes `index.html').
5769 `:index-title' Title of index page. Defaults to name of file.
5770 `:index-function' Plugin function to use for generation of index.
5771 Defaults to `org-publish-org-index', which generates
5772 a plain list of links to all files in the project.
5775 File: org, Node: Sample configuration, Next: Triggering publication, Prev: Configuration, Up: Publishing
5777 12.2 Sample configuration
5778 =========================
5780 Below we provide two example configurations. The first one is a simple
5781 project publishing only a set of Org-mode files. The second example is
5782 more complex, with a multi-component project.
5786 * Simple example:: One-component publishing
5787 * Complex example:: A multi-component publishing example
5790 File: org, Node: Simple example, Next: Complex example, Prev: Sample configuration, Up: Sample configuration
5792 12.2.1 Example: simple publishing configuration
5793 -----------------------------------------------
5795 This example publishes a set of Org-mode files to the `public_html'
5796 directory on the local machine.
5798 (setq org-publish-project-alist
5800 :base-directory "~/org/"
5801 :publishing-directory "~/public_html"
5802 :section-numbers nil
5803 :table-of-contents nil
5804 :style "<link rel=stylesheet
5805 href=\"../other/mystyle.css\"
5806 type=\"text/css\">")))
5809 File: org, Node: Complex example, Prev: Simple example, Up: Sample configuration
5811 12.2.2 Example: complex publishing configuration
5812 ------------------------------------------------
5814 This more complicated example publishes an entire website, including
5815 org files converted to HTML, image files, emacs lisp source code, and
5816 stylesheets. The publishing-directory is remote and private files are
5819 To ensure that links are preserved, care should be taken to replicate
5820 your directory structure on the web server, and to use relative file
5821 paths. For example, if your org files are kept in `~/org' and your
5822 publishable images in `~/images', you'd link to an image with
5823 file:../images/myimage.png
5824 On the web server, the relative path to the image should be the
5825 same. You can accomplish this by setting up an "images" folder in the
5826 right place on the webserver, and publishing images to it.
5828 (setq org-publish-project-alist
5830 :base-directory "~/org/"
5831 :base-extension "org"
5832 :publishing-directory "/ssh:user@host:~/html/notebook/"
5833 :publishing-function org-publish-org-to-html
5834 :exclude "PrivatePage.org" ;; regexp
5836 :section-numbers nil
5837 :table-of-contents nil
5838 :style "<link rel=stylesheet
5839 href=\"../other/mystyle.css\" type=\"text/css\">"
5841 :auto-postamble nil)
5844 :base-directory "~/images/"
5845 :base-extension "jpg\\|gif\\|png"
5846 :publishing-directory "/ssh:user@host:~/html/images/"
5847 :publishing-function org-publish-attachment)
5850 :base-directory "~/other/"
5851 :base-extension "css\\|el"
5852 :publishing-directory "/ssh:user@host:~/html/other/"
5853 :publishing-function org-publish-attachment)
5854 ("website" :components ("orgfiles" "images" "other"))))
5857 File: org, Node: Triggering publication, Prev: Sample configuration, Up: Publishing
5859 12.3 Triggering publication
5860 ===========================
5862 Once org-publish is properly configured, you can publish with the
5863 following functions:
5866 Prompt for a specific project and publish all files that belong to
5870 Publish the project containing the current file.
5873 Publish only the current file.
5876 Publish all projects.
5878 Org uses timestamps to track when a file has changed. The above
5879 functions normally only publish changed files. You can override this and
5880 force publishing of all files by giving a prefix argument.
5883 File: org, Node: Miscellaneous, Next: Extensions and Hacking, Prev: Publishing, Up: Top
5890 * Completion:: M-TAB knows what you need
5891 * Customization:: Adapting Org-mode to your taste
5892 * In-buffer settings:: Overview of the #+KEYWORDS
5893 * The very busy C-c C-c key:: When in doubt, press C-c C-c
5894 * Clean view:: Getting rid of leading stars in the outline
5895 * TTY keys:: Using Org-mode on a tty
5896 * Interaction:: Other Emacs packages
5897 * Bugs:: Things which do not work perfectly
5900 File: org, Node: Completion, Next: Customization, Prev: Miscellaneous, Up: Miscellaneous
5905 Org-mode supports in-buffer completion. This type of completion does
5906 not make use of the minibuffer. You simply type a few letters into the
5907 buffer and use the key to complete text right there.
5910 Complete word at point
5911 * At the beginning of a headline, complete TODO keywords.
5913 * After `\', complete TeX symbols supported by the exporter.
5915 * After `*', complete headlines in the current buffer so that
5916 they can be used in search links like `[[*find this
5919 * After `:' in a headline, complete tags. The list of tags is
5920 taken from the variable `org-tag-alist' (possibly set through
5921 the `#+TAGS' in-buffer option, *note Setting tags::), or it
5922 is created dynamically from all tags used in the current
5925 * After `:' and not in a headline, complete property keys. The
5926 list of keys is constructed dynamically from all keys used in
5929 * After `[', complete link abbreviations (*note Link
5932 * After `#+', complete the special keywords like `TYP_TODO' or
5933 `OPTIONS' which set file-specific options for Org-mode. When
5934 the option keyword is already complete, pressing `M-<TAB>'
5935 again will insert example settings for this keyword.
5937 * In the line after `#+STARTUP: ', complete startup keywords,
5938 i.e. valid keys for this line.
5940 * Elsewhere, complete dictionary words using ispell.
5943 File: org, Node: Customization, Next: In-buffer settings, Prev: Completion, Up: Miscellaneous
5948 There are more than 180 variables that can be used to customize
5949 Org-mode. For the sake of compactness of the manual, I am not
5950 describing the variables here. A structured overview of customization
5951 variables is available with `M-x org-customize'. Or select `Browse Org
5952 Group' from the `Org->Customization' menu. Many settings can also be
5953 activated on a per-file basis, by putting special lines into the buffer
5954 (*note In-buffer settings::).
5957 File: org, Node: In-buffer settings, Next: The very busy C-c C-c key, Prev: Customization, Up: Miscellaneous
5959 13.3 Summary of in-buffer settings
5960 ==================================
5962 Org-mode uses special lines in the buffer to define settings on a
5963 per-file basis. These lines start with a `#+' followed by a keyword, a
5964 colon, and then individual words defining a setting. Several setting
5965 words can be in the same line, but you can also have multiple lines for
5966 the keyword. While these settings are described throughout the manual,
5967 here is a summary. After changing any of those lines in the buffer,
5968 press `C-c C-c' with the cursor still in the line to activate the
5969 changes immediately. Otherwise they become effective only when the
5970 file is visited again in a new Emacs session.
5972 `#+ARCHIVE: %s_done::'
5973 This line sets the archive location for the agenda file. It
5974 applies for all subsequent lines until the next `#+CATEGORY' line,
5975 or the end of the file. The first such line also applies to any
5976 entries before it. The corresponding variable is
5977 `org-archive-location'.
5980 This line sets the category for the agenda file. The category
5981 applies for all subsequent lines until the next `#+CATEGORY' line,
5982 or the end of the file. The first such line also applies to any
5985 `#+COLUMNS: %25ITEM .....'
5986 Set the default format for columns view. This format applies when
5987 columns view is invoked in location where no COLUMNS property
5990 `#+CONSTANTS: name1=value1 ...'
5991 Set file-local values for constants to be used in table formulas.
5992 This line set the local variable
5993 `org-table-formula-constants-local'. The global version of theis
5994 variable is `org-table-formula-constants'. corresponding
5996 `#+LINK: linkword replace'
5997 These lines (several are allowed) specify link abbreviations.
5998 *Note Link abbreviations::. The corresponding variable is
5999 `org-link-abbrev-alist'.
6001 `#+PRIORITIES: highest lowest default'
6002 This line sets the limits and the default for the priorities. All
6003 three must be either letters A-Z or numbers 0-9. The highest
6004 priority must have a lower ASCII number that the lowest priority.
6007 This line sets options to be used at startup of org-mode, when an
6008 Org-mode file is being visited. The first set of options deals
6009 with the initial visibility of the outline tree. The
6010 corresponding variable for global default settings is
6011 `org-startup-folded', with a default value `t', which means
6013 overview top-level headlines only
6014 content all headlines
6015 showall no folding at all, show everything
6016 Then there are options for aligning tables upon visiting a file.
6017 This is useful in files containing narrowed table columns. The
6018 corresponding variable is `org-startup-align-all-tables', with a
6019 default value `nil'.
6020 align align all tables
6021 noalign don't align tables on startup
6022 Logging TODO state changes and clock intervals (variable
6023 `org-log-done') can be configured using these options.
6024 logging record a timestamp when an item is marked DONE
6025 nologging don't record when items are marked DONE
6026 lognotedone record timestamp and a note when DONE
6027 lognotestate record timestamp and a note when TODO state changes
6028 logrepeat record a note when re-instating a repeating item
6029 nologrepeat do not record when re-instating repeating item
6030 lognoteclock-out record timestamp and a note when clocking out
6031 Here are the options for hiding leading stars in outline headings.
6032 The corresponding variables are `org-hide-leading-stars' and
6033 `org-odd-levels-only', both with a default setting `nil' (meaning
6034 `showstars' and `oddeven').
6035 hidestars make all but one of the stars starting a headline invisible.
6036 showstars show all stars starting a headline
6037 odd allow only odd outline levels (1,3,...)
6038 oddeven allow all outline levels
6039 To turn on custom format overlays over time stamps (variables
6040 `org-put-time-stamp-overlays' and
6041 `org-time-stamp-overlay-formats'), use
6042 customtime overlay custom time format
6043 The following options influence the table spreadsheet (variable
6044 `constants-unit-system').
6045 constcgs `constants.el' should use the c-g-s unit system
6046 constSI `constants.el' should use the SI unit system
6048 `#+TAGS: TAG1(c1) TAG2(c2)'
6049 These lines (several such lines are allowed) specify the legal
6050 tags in this file, and (potentially) the corresponding _fast tag
6051 selection_ keys. The corresponding variable is `org-tag-alist'.
6054 This line contains the formulas for the table directly above the
6057 `#+TITLE:, #+AUTHOR:, #+EMAIL:, #+LANGUAGE:, #+TEXT:, #+OPTIONS:'
6058 These lines provide settings for exporting files. For more
6059 details see *Note Export options::.
6061 `#+SEQ_TODO: #+TYP_TODO:'
6062 These lines set the TODO keywords and their interpretation in the
6063 current file. The corresponding variables are `org-todo-keywords'
6064 and `org-todo-interpretation'.
6067 File: org, Node: The very busy C-c C-c key, Next: Clean view, Prev: In-buffer settings, Up: Miscellaneous
6069 13.4 The very busy C-c C-c key
6070 ==============================
6072 The key `C-c C-c' has many purposes in org-mode, which are all
6073 mentioned scattered throughout this manual. One specific function of
6074 this key is to add _tags_ to a headline (*note Tags::). In many other
6075 circumstances it means something like _Hey Org-mode, look here and
6076 update according to what you see here_. Here is a summary of what this
6077 means in different contexts.
6079 - If there are highlights in the buffer from the creation of a sparse
6080 tree, or from clock display, remove these highlights.
6082 - If the cursor is in one of the special `#+KEYWORD' lines, this
6083 triggers scanning the buffer for these lines and updating the
6086 - If the cursor is inside a table, realign the table. This command
6087 works even if the automatic table editor has been turned off.
6089 - If the cursor is on a `#+TBLFM' line, re-apply the formulas to the
6092 - If the cursor is inside a table created by the `table.el' package,
6093 activate that table.
6095 - If the current buffer is a remember buffer, close the note and
6096 file it. With a prefix argument, file it, without further
6097 interaction, to the default location.
6099 - If the cursor is on a `<<<target>>>', update radio targets and
6100 corresponding links in this buffer.
6102 - If the cursor is in a property line or at the start or end of a
6103 property drawer, offer property commands.
6105 - If the cursor is in a plain list item with a checkbox, toggle the
6106 status of the checkbox.
6108 - If the cursor is on a numbered item in a plain list, renumber the
6112 File: org, Node: Clean view, Next: TTY keys, Prev: The very busy C-c C-c key, Up: Miscellaneous
6114 13.5 A cleaner outline view
6115 ===========================
6117 Some people find it noisy and distracting that the Org-mode headlines
6118 are starting with a potentially large number of stars. For example the
6119 tree from *Note Headlines:::
6121 * Top level headline
6127 * Another top level headline
6129 Unfortunately this is deeply ingrained into the code of Org-mode and
6130 cannot be easily changed. You can, however, modify the display in such
6131 a way that all leading stars become invisible and the outline more easy
6132 to read. To do this, customize the variable `org-hide-leading-stars'
6135 (setq org-hide-leading-stars t)
6137 or change this on a per-file basis with one of the lines (anywhere in
6140 #+STARTUP: showstars
6141 #+STARTUP: hidestars
6143 Press `C-c C-c' with the cursor in a `STARTUP' line to activate the
6146 With stars hidden, the tree becomes:
6148 * Top level headline
6154 * Another top level headline
6156 Note that the leading stars are not truly replaced by whitespace, they
6157 are only fontified with the face `org-hide' that uses the background
6158 color as font color. If you are not using either white or black
6159 background, you may have to customize this face to get the wanted
6160 effect. Another possibility is to set this font such that the extra
6161 stars are almost invisible, for example using the color `grey90' on a
6164 Things become cleaner still if you skip all the even levels and use
6165 only odd levels 1, 3, 5..., effectively adding two stars to go from one
6166 outline level to the next:
6168 * Top level headline
6174 * Another top level headline
6176 In order to make the structure editing and export commands handle this
6177 convention correctly, use
6179 (setq org-odd-levels-only t)
6181 or set this on a per-file basis with one of the following lines (don't
6182 forget to press `C-c C-c' with the cursor in the startup line to
6183 activate changes immediately).
6188 You can convert an Org-mode file from single-star-per-level to the
6189 double-star-per-level convention with `M-x org-convert-to-odd-levels
6190 RET' in that file. The reverse operation is `M-x
6191 org-convert-to-oddeven-levels'.
6194 File: org, Node: TTY keys, Next: Interaction, Prev: Clean view, Up: Miscellaneous
6196 13.6 Using org-mode on a tty
6197 ============================
6199 Org-mode uses a number of keys that are not accessible on a tty. This
6200 applies to most special keys like cursor keys, <TAB> and <RET>, when
6201 these are combined with modifier keys like <Meta> and/or <Shift>.
6202 Org-mode uses these bindings because it needs to provide keys for a
6203 large number of commands, and because these keys appeared particularly
6204 easy to remember. In order to still be able to access the core
6205 functionality of Org-mode on a tty, alternative bindings are provided.
6206 Here is a complete list of these bindings, which are obviously more
6207 cumbersome to use. Note that sometimes a work-around can be better.
6208 For example changing a time stamp is really only fun with `S-<cursor>'
6209 keys. On a tty you would rather use `C-c .' to re-insert the
6212 Default Alternative 1 Alternative 2
6213 `S-<TAB>' `C-u <TAB>'
6214 `M-<left>' `C-c C-x l' `<Esc> <left>'
6215 `M-S-<left>'`C-c C-x L'
6216 `M-<right>' `C-c C-x r' `<Esc>
6218 `M-S-<right>'`C-c C-x R'
6219 `M-<up>' `C-c C-x u' `<Esc> <up>'
6220 `M-S-<up>' `C-c C-x U'
6221 `M-<down>' `C-c C-x d' `<Esc> <down>'
6222 `M-S-<down>'`C-c C-x D'
6223 `S-<RET>' `C-c C-x c'
6224 `M-<RET>' `C-c C-x m' `<Esc> <RET>'
6225 `M-S-<RET>' `C-c C-x M'
6226 `S-<left>' `C-c <left>'
6227 `S-<right>' `C-c <right>'
6229 `S-<down>' `C-c <down>'
6230 `C-S-<left>'`C-c C-x
6232 `C-S-<right>'`C-c C-x
6236 File: org, Node: Interaction, Next: Bugs, Prev: TTY keys, Up: Miscellaneous
6238 13.7 Interaction with other packages
6239 ====================================
6241 Org-mode lives in the world of GNU Emacs and interacts in various ways
6242 with other code out there.
6246 * Cooperation:: Packages Org-mode cooperates with
6247 * Conflicts:: Packages that lead to conflicts
6250 File: org, Node: Cooperation, Next: Conflicts, Prev: Interaction, Up: Interaction
6252 13.7.1 Packages that Org-mode cooperates with
6253 ---------------------------------------------
6255 `calc.el' by Dave Gillespie
6256 Org-mode uses the calc package for implementing spreadsheet
6257 functionality in its tables (*note The spreadsheet::). Org-mode
6258 checks for the availability of calc by looking for the function
6259 `calc-eval' which should be autoloaded in your setup if calc has
6260 been installed properly. As of Emacs 22, calc is part of the Emacs
6261 distribution. Another possibility for interaction between the two
6262 packages is using calc for embedded calculations. *Note Embedded
6263 Mode: (calc)Embedded Mode.
6265 `constants.el' by Carsten Dominik
6266 In a table formula (*note The spreadsheet::), it is possible to use
6267 names for natural constants or units. Instead of defining your own
6268 constants in the variable `org-table-formula-constants', install
6269 the `constants' package which defines a large number of constants
6270 and units, and lets you use unit prefixes like `M' for `Mega' etc.
6271 You will need version 2.0 of this package, available at
6272 `http://www.astro.uva.nl/~dominik/Tools'. Org-mode checks for the
6273 function `constants-get', which has to be autoloaded in your
6274 setup. See the installation instructions in the file
6277 `cdlatex.el' by Carsten Dominik
6278 Org-mode can make use of the cdlatex package to efficiently enter
6279 LaTeX fragments into Org-mode files. See *Note CDLaTeX mode::.
6281 `remember.el' by John Wiegley
6282 Org mode cooperates with remember, see *Note Remember::.
6283 `Remember.el' is not part of Emacs, find it on the web.
6285 `table.el' by Takaaki Ota
6286 Complex ASCII tables with automatic line wrapping, column- and
6287 row-spanning, and alignment can be created using the Emacs table
6288 package by Takaaki Ota (`http://sourceforge.net/projects/table',
6289 and also part of Emacs 22). When <TAB> or `C-c C-c' is pressed in
6290 such a table, Org-mode will call `table-recognize-table' and move
6291 the cursor into the table. Inside a table, the keymap of Org-mode
6292 is inactive. In order to execute Org-mode-related commands, leave
6296 Recognize `table.el' table. Works when the cursor is in a
6300 Insert a table.el table. If there is already a table at
6301 point, this command converts it between the table.el format
6302 and the Org-mode format. See the documentation string of the
6303 command `org-convert-table' for the restrictions under which
6305 `table.el' is part of Emacs 22.
6307 `footnote.el' by Steven L. Baur
6308 Org-mode recognizes numerical footnotes as provided by this package
6309 (*note Footnotes::).
6312 File: org, Node: Conflicts, Prev: Cooperation, Up: Interaction
6314 13.7.2 Packages that lead to conflicts with Org-mode
6315 ----------------------------------------------------
6317 `allout.el' by Ken Manheimer
6318 Startup of Org-mode may fail with the error message
6319 `(wrong-type-argument keymapp nil)' when there is an outdated
6320 version `allout.el' on the load path, for example the version
6321 distributed with Emacs 21.x. Upgrade to Emacs 22 and this problem
6322 will disappear. If for some reason you cannot do this, make sure
6323 that org.el is loaded _before_ `allout.el', for example by putting
6324 `(require 'org)' early enough into your `.emacs' file.
6326 `CUA.el' by Kim. F. Storm
6327 Keybindings in Org-mode conflict with the `S-<cursor>' keys used
6328 by CUA-mode (as well as pc-select-mode and s-region-mode) to
6329 select and extend the region. If you want to use one of these
6330 packages along with Org-mode, configure the variable
6331 `org-CUA-compatible'. When set, Org-mode will move the following
6332 keybindings in org-mode files, and in the agenda buffer (but not
6333 during date selection).
6335 S-UP -> M-p S-DOWN -> M-n
6336 S-LEFT -> M-- S-RIGHT -> M-+
6338 Yes, these are unfortunately more difficult to remember. If you
6339 want to have other replacement keys, look at the variable
6340 `org-disputed-keys'.
6342 `windmove.el' by Hovav Shacham
6343 Also this package uses the `S-<cursor>' keys, so everything written
6344 in the paragraph above about CUA mode also applies here.
6346 `footnote.el' by Steven L. Baur
6347 Org-mode supports the syntax of the footnote package, but only the
6348 numerical footnote markers. Also, the default key for footnote
6349 commands, `C-c !' is already used by org-mode. You could use the
6350 variable `footnote-prefix' to switch footnotes commands to another
6351 key. Or, you could use `org-replace-disputed-keys' and
6352 `org-disputed-keys' to change the settings in Org-mode.
6356 File: org, Node: Bugs, Prev: Interaction, Up: Miscellaneous
6361 Here is a list of things that should work differently, but which I have
6362 found too hard to fix.
6364 * If a table field starts with a link, and if the corresponding table
6365 column is narrowed (*note Narrow columns::) to a width too small to
6366 display the link, the field would look entirely empty even though
6367 it is not. To prevent this, Org-mode throws an error. The
6368 work-around is to make the column wide enough to fit the link, or
6369 to add some text (at least 2 characters) before the link in the
6372 * Narrowing table columns does not work on XEmacs, because the
6373 `format' function does not transport text properties.
6375 * Text in an entry protected with the `QUOTE' keyword should not
6378 * When the application called by `C-c C-o' to open a file link fails
6379 (for example because the application does not exist or refuses to
6380 open the file), it does so silently. No error message is
6383 * Recalculating a table line applies the formulas from left to right.
6384 If a formula uses _calculated_ fields further down the row,
6385 multiple recalculation may be needed to get all fields consistent.
6386 You may use the command `org-table-iterate' (`C-u C-c *') to
6387 recalculate until convergence.
6389 * A single letter cannot be made bold, for example `*a*'.
6391 * The exporters work well, but could be made more efficient.
6394 File: org, Node: Extensions and Hacking, Next: History and Acknowledgments, Prev: Miscellaneous, Up: Top
6396 Appendix A Extensions, Hooks and Hacking
6397 ****************************************
6399 This appendix lists extensions for Org-mode written by other authors.
6400 It also covers some aspects where users can extend the functionality of
6405 * Extensions:: Existing 3rd-part extensions
6406 * Tables in arbitrary syntax:: Orgtbl for LaTeX and other programs
6407 * Dynamic blocks:: Automatically filled blocks
6408 * Special agenda views:: Customized views
6409 * Using the property API:: Writing programs that use entry properties
6412 File: org, Node: Extensions, Next: Tables in arbitrary syntax, Prev: Extensions and Hacking, Up: Extensions and Hacking
6414 A.1 Third-party extensions for Org-mode
6415 =======================================
6417 The following extensions for Org-mode have been written by other people:
6419 `org-publish.el' by David O'Toole
6420 This package provides facilities for publishing related sets of
6421 Org-mode files together with linked files like images as webpages.
6422 It is highly configurable and can be used for other publishing
6423 purposes as well. As of Org-mode version 4.30, `org-publish.el'
6424 is part of the Org-mode distribution. It is not yet part of
6425 Emacs, however, a delay caused by the preparations for the 22.1
6426 release. In the mean time, `org-publish.el' can be downloaded
6427 from David's site: `http://dto.freeshell.org/e/org-publish.el'.
6429 `org-mouse.el' by Piotr Zielinski
6430 This package implements extended mouse functionality for Org-mode.
6431 It allows you to cycle visibility and to edit the document
6432 structure with the mouse. Best of all, it provides a
6433 context-sensitive menu on <mouse-3> that changes depending on the
6434 context of a mouse-click. As of Org-mode version 4.53,
6435 `org-mouse.el' is part of the Org-mode distribution. It is not
6436 yet part of Emacs, however, a delay caused by the preparations for
6437 the 22.1 release. In the mean time, `org-mouse.el' can be
6438 downloaded from Piotr's site:
6439 `http://www.cl.cam.ac.uk/~pz215/files/org-mouse.el'.
6441 `org-blog.el' by David O'Toole
6442 A blogging plug-in for `org-publish.el'.
6443 `http://dto.freeshell.org/notebook/OrgMode.html'.
6445 `blorg.el' by Bastien Guerry
6446 Publish Org-mode files as blogs.
6447 `http://www.cognition.ens.fr/~guerry/blorg.html'.
6449 `org2rem.el' by Bastien Guerry
6450 Translates Org-mode files into something readable by Remind.
6451 `http://www.cognition.ens.fr/~guerry/u/org2rem.el'.
6454 File: org, Node: Tables in arbitrary syntax, Next: Dynamic blocks, Prev: Extensions, Up: Extensions and Hacking
6456 A.2 Tables in arbitrary syntax
6457 ==============================
6459 Since Orgtbl-mode can be used as a minor mode in arbitrary buffers, a
6460 frequent feature request has been to make it work with native tables in
6461 specific languages, for example LaTeX. However, this is extremely hard
6462 to do in a general way, would lead to a customization nightmare, and
6463 would take away much of the simplicity of the Orgtbl-mode table editor.
6465 This appendix describes a different approach. We keep the
6466 Orgtbl-mode table in its native format (the source table), and use a
6467 custom function to translate the table to the correct syntax, and to
6468 install it in the right location (the target table). This puts the
6469 burden of writing conversion functions on the user, but it allows for a
6470 very flexible system.
6474 * Radio tables:: Sending and receiving
6475 * A LaTeX example:: Step by step, almost a tutorial
6476 * Translator functions:: Copy and modify
6479 File: org, Node: Radio tables, Next: A LaTeX example, Prev: Tables in arbitrary syntax, Up: Tables in arbitrary syntax
6484 To define the location of the target table, you first need to create two
6485 lines that are comments in the current mode, but contain magic words for
6486 Orgtbl-mode to find. Orgtbl-mode will insert the translated table
6487 between these lines, replacing whatever was there before. For example:
6489 /* BEGIN RECEIVE ORGTBL table_name */
6490 /* END RECEIVE ORGTBL table_name */
6492 Just above the source table, we put a special line that tells
6493 Orgtbl-mode how to translate this table and where to install it. For
6495 #+ORGTBL: SEND table_name translation_function arguments....
6497 `table_name' is the reference name for the table that is also used in
6498 the receiver lines. `translation_function' is the Lisp function that
6499 does the translation. Furthermore, the line can contain a list of
6500 arguments (alternating key and value) at the end. The arguments will be
6501 passed as a property list to the translation function for
6502 interpretation. A few standard parameters are already recognized and
6503 acted upon before the translation function is called:
6506 Skip the first N lines of the table. Hlines do count!
6508 `:skipcols (n1 n2 ...)'
6509 List of columns that should be skipped. If the table has a column
6510 with calculation marks, that column is automatically discarded as
6511 well. Please note that the translator function sees the table
6512 _after_ the removal of these columns, the function never knows
6513 that there have been additional columns.
6515 The one problem remaining is how to keep the source table in the buffer
6516 without disturbing the normal workings of the file, for example during
6517 compilation of a C file or processing of a LaTeX file. There are a
6518 number of different solutions:
6520 * The table could be placed in a block comment if that is supported
6521 by the language. For example, in C-mode you could wrap the table
6522 between `/*' and `*/' lines.
6524 * Sometimes it is possible to put the table after some kind of END
6525 statement, for example `\bye' in TeX and `\end{document}' in LaTeX.
6527 * You can just comment the table line by line whenever you want to
6528 process the file, and uncomment it whenever you need to edit the
6529 table. This only sounds tedious - the command `M-x
6530 orgtbl-toggle-comment' does make this comment-toggling very easy,
6531 in particular if you bind it to a key.
6534 File: org, Node: A LaTeX example, Next: Translator functions, Prev: Radio tables, Up: Tables in arbitrary syntax
6536 A.2.2 A LaTeX example
6537 ---------------------
6539 The best way to wrap the source table in LaTeX is to use the `comment'
6540 environment provided by `comment.sty'. It has to be activated by
6541 placing `\usepackage{comment}' into the document header. Orgtbl-mode
6542 can insert a radio table skeleton(1) with the command `M-x
6543 orgtbl-insert-radio-table'. You will be prompted for a table name,
6544 lets say we use `salesfigures'. You will then get the following
6547 % BEGIN RECEIVE ORGTBL salesfigures
6548 % END RECEIVE ORGTBL salesfigures
6550 #+ORGTBL: SEND salesfigures orgtbl-to-latex
6554 The `#+ORGTBL: SEND' line tells orgtbl-mode to use the function
6555 `orgtbl-to-latex' to convert the table into LaTeX and to put it into
6556 the receiver location with name `salesfigures'. You may now fill in
6557 the table, feel free to use the spreadsheet features(2):
6559 % BEGIN RECEIVE ORGTBL salesfigures
6560 % END RECEIVE ORGTBL salesfigures
6562 #+ORGTBL: SEND salesfigures orgtbl-to-latex
6563 | Month | Days | Nr sold | per day |
6564 |-------+------+---------+---------|
6565 | Jan | 23 | 55 | 2.4 |
6566 | Feb | 21 | 16 | 0.8 |
6567 | March | 22 | 278 | 12.6 |
6568 #+TBLFM: $4=$3/$2;%.1f
6569 % $ (optional extra dollar to keep font-lock happy, see footnote)
6572 When you are done, press `C-c C-c' in the table to get the converted
6573 table inserted between the two marker lines.
6575 Now lets assume you want to make the table header by hand, because
6576 you want to control how columns are aligned etc. In this case we make
6577 sure that the table translator does skip the first 2 lines of the source
6578 table, and tell the command to work as a splice, i.e. to not produce
6579 header and footer commands of the target table:
6581 \begin{tabular}{lrrr}
6582 Month & \multicolumn{1}{c}{Days} & Nr.\ sold & per day\\
6583 % BEGIN RECEIVE ORGTBL salesfigures
6584 % END RECEIVE ORGTBL salesfigures
6588 #+ORGTBL: SEND salesfigures orgtbl-to-latex :splice t :skip 2
6589 | Month | Days | Nr sold | per day |
6590 |-------+------+---------+---------|
6591 | Jan | 23 | 55 | 2.4 |
6592 | Feb | 21 | 16 | 0.8 |
6593 | March | 22 | 278 | 12.6 |
6594 #+TBLFM: $4=$3/$2;%.1f
6597 The LaTeX translator function `orgtbl-to-latex' is already part of
6598 Orgtbl-mode. It uses a `tabular' environment to typeset the table and
6599 marks horizontal lines with `\hline'. Furthermore, it interprets the
6600 following parameters:
6603 When set to t, return only table body lines, don't wrap them into a
6604 tabular environment. Default is nil.
6607 A format to be used to wrap each field, should contain `%s' for the
6608 original field value. For example, to wrap each field value in
6609 dollars, you could use `:fmt "$%s$"'. This may also be a property
6610 list with column numbers and formats. for example `:fmt (2 "$%s$"
6614 Use this format to print numbers with exponentials. The format
6615 should have `%s' twice for inserting mantissa and exponent, for
6616 example `"%s\\times10^{%s}"'. The default is `"%s\\,(%s)"'. This
6617 may also be a property list with column numbers and formats, for
6618 example `:efmt (2 "$%s\\times10^{%s}$" 4 "$%s\\cdot10^{%s}$")'.
6619 After `efmt' has been applied to a value, `fmt' will also be
6622 ---------- Footnotes ----------
6624 (1) By default this works only for LaTeX, HTML, and TeXInfo.
6625 Configure the variable `orgtbl-radio-tables' to install templates for
6628 (2) If the `#+TBLFM' line contains an odd number of dollar
6629 characters, this may cause problems with font-lock in latex-mode. As
6630 shown in the example you can fix this by adding an extra line inside the
6631 `comment' environment that is used to balance the dollar expressions.
6632 If you are using AUCTeX with the font-latex library, a much better
6633 solution is to add the `comment' environment to the variable
6634 `LaTeX-verbatim-environments'.
6637 File: org, Node: Translator functions, Prev: A LaTeX example, Up: Tables in arbitrary syntax
6639 A.2.3 Translator functions
6640 --------------------------
6642 Orgtbl-mode has several translator functions built-in:
6643 `orgtbl-to-latex', `orgtbl-to-html', and `orgtbl-to-texinfo'. Except
6644 for `orgtbl-to-html'(1), these all use a generic translator,
6645 `orgtbl-to-generic'. For example, `orgtbl-to-latex' itself is a very
6646 short function that computes the column definitions for the `tabular'
6647 environment, defines a few field and line separators and then hands
6648 over to the generic translator. Here is the entire code:
6650 (defun orgtbl-to-latex (table params)
6651 "Convert the orgtbl-mode TABLE to LaTeX."
6652 (let* ((alignment (mapconcat (lambda (x) (if x "r" "l"))
6653 org-table-last-alignment ""))
6656 :tstart (concat "\\begin{tabular}{" alignment "}")
6657 :tend "\\end{tabular}"
6658 :lstart "" :lend " \\\\" :sep " & "
6659 :efmt "%s\\,(%s)" :hline "\\hline")))
6660 (orgtbl-to-generic table (org-combine-plists params2 params))))
6662 As you can see, the properties passed into the function (variable
6663 PARAMS) are combined with the ones newly defined in the function
6664 (variable PARAMS2). The ones passed into the function (i.e. the ones
6665 set by the `ORGTBL SEND' line) take precedence. So if you would like
6666 to use the LaTeX translator, but wanted the line endings to be
6667 `\\[2mm]' instead of the default `\\', you could just overrule the
6670 #+ORGTBL: SEND test orgtbl-to-latex :lend " \\\\[2mm]"
6672 For a new language, you can either write your own converter function
6673 in analogy with the LaTeX translator, or you can use the generic
6674 function directly. For example, if you have a language where a table
6675 is started with `!BTBL!', ended with `!ETBL!', and where table lines are
6676 started with `!BL!', ended with `!EL!' and where the field separator is
6677 a TAB, you could call the generic translator like this (on a single
6680 #+ORGTBL: SEND test orgtbl-to-generic :tstart "!BTBL!" :tend "!ETBL!"
6681 :lstart "!BL! " :lend " !EL!" :sep "\t"
6683 Please check the documentation string of the function
6684 `orgtbl-to-generic' for a full list of parameters understood by that
6685 function and remember that you can pass each of them into
6686 `orgtbl-to-latex', `orgtbl-to-texinfo', and any other function using
6687 the generic function.
6689 Of course you can also write a completely new function doing
6690 complicated things the generic translator cannot do. A translator
6691 function takes two arguments. The first argument is the table, a list
6692 of lines, each line either the symbol `hline' or a list of fields. The
6693 second argument is the property list containing all parameters
6694 specified in the `#+ORGTBL: SEND' line. The function must return a
6695 single string containing the formatted table. If you write a generally
6696 useful translator, please post it on `emacs-orgmode@gnu.org' so that
6697 others can benefit from your work.
6699 ---------- Footnotes ----------
6701 (1) The HTML translator uses the same code that produces tables
6705 File: org, Node: Dynamic blocks, Next: Special agenda views, Prev: Tables in arbitrary syntax, Up: Extensions and Hacking
6710 Org-mode documents can contain _dynamic blocks_. These are specially
6711 marked regions that are updated by some user-written function. A good
6712 example for such a block is the clock table inserted by the command
6713 `C-c C-x C-r' (*note Clocking work time::).
6715 Dynamic block are enclosed by a BEGIN-END structure that assigns a
6716 name to the block and can also specify parameters for the function
6717 producing the content of the block.
6719 #+BEGIN: myblock :parameter1 value1 :parameter2 value2 ...
6723 Dynamic blocks are updated with the following commands
6726 Update dynamic block at point.
6729 Update all dynamic blocks in the current file.
6731 Updating a dynamic block means to remove all the text between BEGIN
6732 and END, parse the BEGIN line for parameters and then call the specific
6733 writer function for this block to insert the new content. For a block
6734 with name `myblock', the writer function is `org-dblock-write:myblock'
6735 with as only parameter a property list with the parameters given in the
6736 begin line. Here is a trivial example of a block that keeps track of
6737 when the block update function was last run:
6739 #+BEGIN: block-update-time :format "on %m/%d/%Y at %H:%M"
6743 The corresponding block writer function could look like this:
6745 (defun org-dblock-write:block-update-time (params)
6746 (let ((fmt (or (plist-get params :format) "%d. %m. %Y")))
6747 (insert "Last block update at: "
6748 (format-time-string fmt (current-time)))))
6750 If you want to make sure that all dynamic blocks are always
6751 up-to-date, you could add the function `org-update-all-dblocks' to a
6752 hook, for example `before-save-hook'. `org-update-all-dblocks' is
6753 written in a way that is does nothing in buffers that are not in
6757 File: org, Node: Special agenda views, Next: Using the property API, Prev: Dynamic blocks, Up: Extensions and Hacking
6759 A.4 Special Agenda Views
6760 ========================
6762 Org-mode provides a special hook that can be used to narrow down the
6763 selection made by any of the agenda views. You may specify a function
6764 that is used at each match to verify if the match should indeed be part
6765 of the agenda view, and if not, how much should be skipped.
6767 Let's say you want to produce a list of projects that contain a
6768 WAITING tag anywhere in the project tree. Let's further assume that
6769 you have marked all tree headings that define a project with the todo
6770 keyword PROJECT. In this case you would run a todo search for the
6771 keyword PROJECT, but skip the match unless there is a WAITING tag
6772 anywhere in the subtree belonging to the project line.
6774 To achieve this, you must write a function that searches the subtree
6775 for the tag. If the tag is found, the function must return `nil' to
6776 indicate that this match should not be skipped. If there is no such
6777 tag, return the location of the end of the subtree, to indicate that
6778 search should continue from there.
6780 (defun my-skip-unless-waiting ()
6781 "Skip trees that are not waiting"
6782 (let ((subtree-end (save-excursion (org-end-of-subtree t))))
6783 (if (re-search-forward ":WAITING:" subtree-end t)
6784 nil ; tag found, do not skip
6785 subtree-end))) ; tag not found, continue after end of subtree
6787 Furthermore you must write a command that uses `let' to temporarily
6788 put this function into the variable `org-agenda-skip-function', sets
6789 the header string for the agenda buffer, and calls the todo-list
6790 generator while asking for the specific TODO keyword PROJECT. The
6791 function must also accept one argument MATCH, but it can choose to
6792 ignore it(1) (as we do in the example below). Here is the example:
6794 (defun my-org-waiting-projects (&optional match)
6795 "Produce a list of projects that contain a WAITING tag.
6796 MATCH is being ignored."
6798 (let ((org-agenda-skip-function 'my-skip-unless-waiting)
6799 (org-agenda-overriding-header "Projects waiting for something: "))
6801 (org-todo-list "PROJECT")))
6803 ---------- Footnotes ----------
6805 (1) MATCH must be present in case you want to define a custom
6806 command for producing this special list. Custom commands always supply
6807 the MATCH argument, but it can be empty if you do not specify it while
6808 defining the command(*note Custom agenda views::).
6811 File: org, Node: Using the property API, Prev: Special agenda views, Up: Extensions and Hacking
6813 A.5 Using the property API
6814 ==========================
6816 Here is a description of the functions that can be used to work with
6819 -- Function: org-entry-properties &optional pom which
6820 Get all properties of the entry at point-or-marker POM. This
6821 includes the TODO keyword, the tags, time strings for deadline,
6822 scheduled, and clocking, and any additional properties defined in
6823 the entry. The return value is an alist, keys may occur multiple
6824 times if the property key was used several times. POM may also be
6825 nil, in which case the current entry is used. If WHICH is nil or
6826 `all', get all properties. If WHICH is `special' or `standard',
6827 only get that subclass.
6829 -- Function: org-entry-get pom property &optional inherit
6830 Get value of PROPERTY for entry at point-or-marker POM. If
6831 INHERIT is non-nil and the entry does not have the property, then
6832 also check higher levels of the hierarchy.
6834 -- Function: org-entry-delete pom property
6835 Delete the property PROPERTY from entry at point-or-marker POM.
6837 -- Function: org-entry-put pom property value
6838 Set PROPERTY to VALUE for entry at point-or-marker POM.
6840 -- Function: org-buffer-property-keys &optional include-specials
6841 Get all property keys in the current buffer.
6843 -- Function: org-insert-property-drawer
6844 Insert a property drawer at point.
6847 File: org, Node: History and Acknowledgments, Next: Index, Prev: Extensions and Hacking, Up: Top
6849 Appendix B History and Acknowledgments
6850 **************************************
6852 Org-mode was borne in 2003, out of frustration over the user interface
6853 of the Emacs outline-mode. I was trying to organize my notes and
6854 projects, and using Emacs seemed to be the natural way to go. However,
6855 having to remember eleven different commands with two or three keys per
6856 command, only to hide and unhide parts of the outline tree, that seemed
6857 entirely unacceptable to me. Also, when using outlines to take notes, I
6858 constantly want to restructure the tree, organizing it parallel to my
6859 thoughts and plans. _Visibility cycling_ and _structure editing_ were
6860 originally implemented in the package `outline-magic.el', but quickly
6861 moved to the more general `org.el'. As this environment became
6862 comfortable for project planning, the next step was adding _TODO
6863 entries_, basic _time stamps_, and _table support_. These areas
6864 highlight the two main goals that Org-mode still has today: To create a
6865 new, outline-based, plain text mode with innovative and intuitive
6866 editing features, and to incorporate project planning functionality
6867 directly into a notes file.
6869 Since the first release, literally thousands of emails to me or on
6870 `emacs-orgmode@gnu.org' have provided a constant stream of bug reports,
6871 feedback, new ideas, and sometimes patches and add-on code. Many
6872 thanks to everyone who has helped to improve this package. I am trying
6873 to keep here a list of the people who had significant influence in
6874 shaping one or more aspects of Org-mode. The list may not be complete,
6875 if I have forgotten someone, please accept my apologies and let me know.
6877 * Russel Adams came up with the idea for drawers.
6879 * Thomas Baumann contributed the code for links to the MH-E email
6882 * Alex Bochannek provided a patch for rounding time stamps.
6884 * Charles Cave's suggestion sparked the implementation of templates
6887 * Pavel Chalmoviansky influenced the agenda treatment of items with
6890 * Gregory Chernov patched support for lisp forms into table
6891 calculations and improved XEmacs compatibility, in particular by
6892 porting `nouline.el' to XEmacs.
6894 * Sacha Chua suggested to copy some linking code from Planner.
6896 * Eddward DeVilla proposed and tested checkbox statistics. He also
6897 came up with the idea of properties, and that there should be an
6900 * Kees Dullemond used to edit projects lists directly in HTML and so
6901 inspired some of the early development, including HTML export. He
6902 also asked for a way to narrow wide table columns.
6904 * Christian Egli converted the documentation into TeXInfo format,
6905 patched CSS formatting into the HTML exporter, and inspired the
6908 * David Emery provided a patch for custom CSS support in exported
6911 * Nic Ferrier contributed mailcap and XOXO support.
6913 * John Foerch figured out how to make incremental search show context
6914 around a match in a hidden outline tree.
6916 * Niels Giessen had the idea to automatically archive DONE trees.
6918 * Bastien Guerry provided extensive feedback and some patches, and
6919 translated David O'Toole's tutorial into French.
6921 * Kai Grossjohann pointed out key-binding conflicts with other
6924 * Scott Jaderholm proposed footnotes, control over whitespace between
6925 folded entries, and column view for properties.
6927 * Shidai Liu ("Leo") asked for embedded LaTeX and tested it. He also
6928 provided frequent feedback and some patches.
6930 * Jason F. McBrayer suggested agenda export to CSV format.
6932 * Dmitri Minaev sent a patch to set priority limits on a per-file
6935 * Stefan Monnier provided a patch to keep the Emacs-Lisp compiler
6938 * Rick Moynihan proposed to allow multiple TODO sequences in a file.
6940 * Todd Neal provided patches for links to Info files and elisp forms.
6942 * Tim O'Callaghan suggested in-file links, search options for general
6943 file links, and TAGS.
6945 * Takeshi Okano translated the manual and David O'Toole's tutorial
6948 * Oliver Oppitz suggested multi-state TODO items.
6950 * Scott Otterson sparked the introduction of descriptive text for
6951 links, among other things.
6953 * Pete Phillips helped during the development of the TAGS feature,
6954 and provided frequent feedback.
6956 * T.V. Raman reported bugs and suggested improvements.
6958 * Matthias Rempe (Oelde) provided ideas, Windows support, and quality
6961 * Kevin Rogers contributed code to access VM files on remote hosts.
6963 * Frank Ruell solved the mystery of the `keymapp nil' bug, a
6964 conflict with `allout.el'.
6966 * Jason Riedy sent a patch to fix a bug with export of TODO keywords.
6968 * Philip Rooke created the Org-mode reference card and provided lots
6971 * Christian Schlauer proposed angular brackets around links, among
6974 * Linking to VM/BBDB/GNUS was inspired by Tom Shannon's
6975 `organizer-mode.el'.
6977 * Daniel Sinder came up with the idea of internal archiving by
6980 * Dale Smith proposed link abbreviations.
6982 * David O'Toole wrote `org-publish.el' and drafted the manual
6983 chapter about publishing.
6985 * Ju"rgen Vollmer contributed code generating the table of contents
6988 * Chris Wallace provided a patch implementing the `QUOTE' keyword.
6990 * David Wainberg suggested archiving, and improvements to the linking
6993 * John Wiegley wrote `emacs-wiki.el' and `planner.el'. The
6994 development of Org-mode was fully independent, and both systems are
6995 really different beasts in their basic ideas and implementation
6996 details. I later looked at John's code, however, and learned from
6997 his implementation of (i) links where the link itself is hidden
6998 and only a description is shown, and (ii) popping up a calendar to
7001 * Carsten Wimmer suggested some changes and helped fix a bug in
7004 * Roland Winkler requested additional keybindings to make Org-mode
7007 * Piotr Zielinski wrote `org-mouse.el', proposed agenda blocks and
7008 contributed various ideas and code snippets.
7011 File: org, Node: Index, Next: Key Index, Prev: History and Acknowledgments, Up: Top
7019 * abbreviation, links: Link abbreviations. (line 6)
7020 * acknowledgments: History and Acknowledgments.
7022 * action, for publishing: Publishing action. (line 6)
7023 * activation: Activation. (line 6)
7024 * active region <1>: Export commands. (line 6)
7025 * active region <2>: ASCII export. (line 9)
7026 * active region <3>: Built-in table editor.
7028 * active region: Structure editing. (line 64)
7029 * agenda: Weekly/Daily agenda. (line 6)
7030 * agenda dispatcher: Agenda dispatcher. (line 6)
7031 * agenda files: Agenda files. (line 6)
7032 * agenda files, removing buffers: Agenda commands. (line 239)
7033 * agenda views: Agenda views. (line 6)
7034 * agenda views, custom: Custom agenda views. (line 6)
7035 * agenda views, exporting <1>: Exporting Agenda Views.
7037 * agenda views, exporting: Agenda commands. (line 228)
7038 * agenda views, user-defined: Special agenda views.
7040 * agenda, pipe: Extracting Agenda Information for other programs.
7042 * agenda, with block views: Block agenda. (line 6)
7043 * align, STARTUP keyword: In-buffer settings. (line 63)
7044 * allout.el: Conflicts. (line 6)
7045 * angular brackets, around links: External links. (line 43)
7046 * API, for properties <1>: Using the property API.
7048 * API, for properties: Property API. (line 6)
7049 * archive locations: Moving subtrees. (line 21)
7050 * archiving: Archiving. (line 6)
7051 * ASCII export: ASCII export. (line 6)
7052 * author: Feedback. (line 6)
7053 * autoload: Activation. (line 6)
7054 * backtrace of an error: Feedback. (line 27)
7055 * BBDB links: External links. (line 6)
7056 * block agenda: Block agenda. (line 6)
7057 * blorg.el: Extensions. (line 32)
7058 * bold text: Enhancing text. (line 15)
7059 * Boolean logic, for tag searches: Tag searches. (line 23)
7060 * bug reports: Feedback. (line 6)
7061 * bugs: Bugs. (line 6)
7062 * C-c C-c, overview: The very busy C-c C-c key.
7064 * calc package: The spreadsheet. (line 6)
7065 * calc.el: Cooperation. (line 6)
7066 * calculations, in tables <1>: The spreadsheet. (line 6)
7067 * calculations, in tables: Built-in table editor.
7069 * calendar commands, from agenda: Agenda commands. (line 191)
7070 * calendar integration: Weekly/Daily agenda. (line 24)
7071 * calendar, for selecting date: The date/time prompt.
7073 * category: Categories. (line 6)
7074 * CDLaTeX: CDLaTeX mode. (line 6)
7075 * cdlatex.el: Cooperation. (line 29)
7076 * checkbox statistics: Checkboxes. (line 23)
7077 * checkboxes: Checkboxes. (line 6)
7078 * children, subtree visibility state: Visibility cycling. (line 10)
7079 * clean outline view: Clean view. (line 6)
7080 * column formula: Column formulas. (line 6)
7081 * column view, for properties: Defining columns. (line 6)
7082 * commands, in agenda buffer: Agenda commands. (line 6)
7083 * comment lines: Comment lines. (line 6)
7084 * completion, of dictionary words: Completion. (line 6)
7085 * completion, of file names: Handling links. (line 43)
7086 * completion, of link abbreviations: Completion. (line 6)
7087 * completion, of links: Handling links. (line 25)
7088 * completion, of option keywords <1>: Completion. (line 6)
7089 * completion, of option keywords <2>: Export options. (line 6)
7090 * completion, of option keywords: Per file keywords. (line 23)
7091 * completion, of property keys: Completion. (line 6)
7092 * completion, of tags <1>: Completion. (line 6)
7093 * completion, of tags: Setting tags. (line 11)
7094 * completion, of TeX symbols: Completion. (line 6)
7095 * completion, of TODO keywords <1>: Completion. (line 6)
7096 * completion, of TODO keywords: Workflow states. (line 15)
7097 * constants, in calculations: References. (line 82)
7098 * constants.el: Cooperation. (line 14)
7099 * constcgs, STARTUP keyword: In-buffer settings. (line 88)
7100 * constSI, STARTUP keyword: In-buffer settings. (line 88)
7101 * content, STARTUP keyword: In-buffer settings. (line 56)
7102 * contents, global visibility state: Visibility cycling. (line 22)
7103 * copying, of subtrees: Structure editing. (line 6)
7104 * creating timestamps: Creating timestamps. (line 6)
7105 * CUA.el: Conflicts. (line 15)
7106 * custom agenda views: Custom agenda views. (line 6)
7107 * custom date/time format: Custom time format. (line 6)
7108 * custom search strings: Custom searches. (line 6)
7109 * customization: Customization. (line 6)
7110 * customtime, STARTUP keyword: In-buffer settings. (line 85)
7111 * cutting, of subtrees: Structure editing. (line 6)
7112 * cycling, of TODO states: TODO basics. (line 13)
7113 * cycling, visibility: Visibility cycling. (line 6)
7114 * daily agenda: Weekly/Daily agenda. (line 6)
7115 * date format, custom: Custom time format. (line 6)
7116 * date range: Time stamps. (line 41)
7117 * date stamps <1>: Time stamps. (line 6)
7118 * date stamps: Timestamps. (line 6)
7119 * date, reading in minibuffer: The date/time prompt.
7121 * DEADLINE keyword: Deadlines and scheduling.
7123 * deadlines: Time stamps. (line 6)
7124 * debugging, of table formulas: Editing and debugging formulas.
7126 * demotion, of subtrees: Structure editing. (line 6)
7127 * diary entries, creating from agenda: Agenda commands. (line 196)
7128 * diary integration: Weekly/Daily agenda. (line 24)
7129 * dictionary word completion: Completion. (line 6)
7130 * directories, for publishing: Sources and destinations.
7132 * dispatching agenda commands: Agenda dispatcher. (line 6)
7133 * display changing, in agenda: Agenda commands. (line 65)
7134 * document structure: Document structure. (line 6)
7135 * DONE, final TODO keyword: Per file keywords. (line 26)
7136 * drawer, for properties: Property syntax. (line 6)
7137 * drawers: Drawers. (line 6)
7138 * dynamic blocks: Dynamic blocks. (line 6)
7139 * editing tables: Tables. (line 6)
7140 * editing, of table formulas: Editing and debugging formulas.
7142 * elisp links: External links. (line 6)
7143 * emphasized text: Export options. (line 25)
7144 * enhancing text: Enhancing text. (line 6)
7145 * evaluate time range: Creating timestamps. (line 48)
7146 * even, STARTUP keyword: In-buffer settings. (line 78)
7147 * exporting: Exporting. (line 6)
7148 * exporting agenda views <1>: Exporting Agenda Views.
7150 * exporting agenda views: Agenda commands. (line 228)
7151 * exporting, not: Comment lines. (line 6)
7152 * extended TODO keywords: TODO extensions. (line 6)
7153 * extension, third-party: Extensions. (line 6)
7154 * external archiving: Moving subtrees. (line 6)
7155 * external links: External links. (line 6)
7156 * external links, in HTML export: Links. (line 6)
7157 * FAQ: Summary. (line 56)
7158 * feedback: Feedback. (line 6)
7159 * field formula: Field formulas. (line 6)
7160 * field references: References. (line 15)
7161 * file links: External links. (line 6)
7162 * file links, searching: Search options. (line 6)
7163 * file name completion: Handling links. (line 43)
7164 * files for agenda: Agenda files. (line 6)
7165 * files, adding to agenda list: Agenda files. (line 12)
7166 * files, selecting for publishing: Selecting files. (line 6)
7167 * fixed width: Enhancing text. (line 28)
7168 * fixed-width sections: Export options. (line 25)
7169 * folded, subtree visibility state: Visibility cycling. (line 10)
7170 * folding, sparse trees: Sparse trees. (line 6)
7171 * following links: Handling links. (line 58)
7172 * footnote.el <1>: Conflicts. (line 35)
7173 * footnote.el <2>: Cooperation. (line 56)
7174 * footnote.el: Footnotes. (line 6)
7175 * footnotes <1>: Export options. (line 25)
7176 * footnotes: Footnotes. (line 6)
7177 * format specifier: Formula syntax for Calc.
7179 * format, of links: Link format. (line 6)
7180 * formula debugging: Editing and debugging formulas.
7182 * formula editing: Editing and debugging formulas.
7184 * formula syntax, Calc: Formula syntax for Calc.
7186 * formula, for individual table field: Field formulas. (line 6)
7187 * formula, for table column: Column formulas. (line 6)
7188 * formula, in tables: Built-in table editor.
7190 * global cycling: Visibility cycling. (line 22)
7191 * global keybindings: Activation. (line 6)
7192 * global TODO list: Global TODO list. (line 6)
7193 * global visibility states: Visibility cycling. (line 22)
7194 * GNUS links: External links. (line 6)
7195 * grouping columns in tables: Column groups. (line 6)
7196 * hand-formatted lists: Enhancing text. (line 11)
7197 * headline levels: Export options. (line 25)
7198 * headline levels, for exporting <1>: Export commands. (line 34)
7199 * headline levels, for exporting: ASCII export. (line 18)
7200 * headline navigation: Motion. (line 6)
7201 * headline tagging: Tags. (line 6)
7202 * headline, promotion and demotion: Structure editing. (line 6)
7203 * headlines: Headlines. (line 6)
7204 * hide text: Visibility cycling. (line 6)
7205 * hidestars, STARTUP keyword: In-buffer settings. (line 78)
7206 * hiding leading stars: Clean view. (line 6)
7207 * history: History and Acknowledgments.
7209 * horizontal rules, in exported files: Enhancing text. (line 18)
7210 * HTML export: HTML export. (line 6)
7211 * HTML, and orgtbl-mode: Translator functions.
7213 * hyperlinks: Hyperlinks. (line 6)
7214 * iCalendar export: iCalendar export. (line 6)
7215 * images, inline in HTML: Images. (line 6)
7216 * in-buffer settings: In-buffer settings. (line 6)
7217 * inactive timestamp: Time stamps. (line 50)
7218 * index, of published pages: Project page index. (line 6)
7219 * Info links: External links. (line 6)
7220 * inheritance, of tags: Tag inheritance. (line 6)
7221 * inlining images in HTML: Images. (line 6)
7222 * inserting links: Handling links. (line 25)
7223 * installation: Installation. (line 6)
7224 * internal archiving: ARCHIVE tag. (line 6)
7225 * internal links: Internal links. (line 6)
7226 * internal links, in HTML export: Links. (line 6)
7227 * introduction: Introduction. (line 6)
7228 * italic text: Enhancing text. (line 15)
7229 * jumping, to headlines: Motion. (line 6)
7230 * keybindings, global: Activation. (line 6)
7231 * keyword options: Per file keywords. (line 6)
7232 * LaTeX fragments <1>: Export options. (line 25)
7233 * LaTeX fragments: LaTeX fragments. (line 6)
7234 * LaTeX fragments, export: Enhancing text. (line 21)
7235 * LaTeX fragments, preview: Processing LaTeX fragments.
7237 * LaTeX interpretation: Embedded LaTeX. (line 6)
7238 * LaTeX, and orgtbl-mode: A LaTeX example. (line 6)
7239 * level, require for tags match: Tag searches. (line 68)
7240 * linebreak preservation: Export options. (line 25)
7241 * linebreak, forced: Enhancing text. (line 35)
7242 * link abbreviations: Link abbreviations. (line 6)
7243 * link abbreviations, completion of: Completion. (line 6)
7244 * link completion: Handling links. (line 25)
7245 * link format: Link format. (line 6)
7246 * links, external: External links. (line 6)
7247 * links, finding next/previous: Handling links. (line 91)
7248 * links, handling: Handling links. (line 6)
7249 * links, in HTML export: Links. (line 6)
7250 * links, internal: Internal links. (line 6)
7251 * links, publishing: Publishing links. (line 6)
7252 * links, radio targets: Radio targets. (line 6)
7253 * links, returning to: Handling links. (line 85)
7254 * Lisp forms, as table formulas: Formula syntax for Lisp.
7256 * lists, hand-formatted: Enhancing text. (line 11)
7257 * lists, ordered: Plain lists. (line 6)
7258 * lists, plain: Plain lists. (line 6)
7259 * logdone, STARTUP keyword: In-buffer settings. (line 67)
7260 * logging, of progress: Progress logging. (line 6)
7261 * lognoteclock-out, STARTUP keyword: In-buffer settings. (line 67)
7262 * lognotedone, STARTUP keyword: In-buffer settings. (line 67)
7263 * lognotestate, STARTUP keyword: In-buffer settings. (line 67)
7264 * logrepeat, STARTUP keyword: In-buffer settings. (line 67)
7265 * maintainer: Feedback. (line 6)
7266 * mark ring: Handling links. (line 81)
7267 * marking characters, tables: Advanced features. (line 40)
7268 * matching, of properties: Matching tags and properties.
7270 * matching, of tags: Matching tags and properties.
7272 * matching, tags: Tags. (line 6)
7273 * math symbols: Math symbols. (line 6)
7274 * MH-E links: External links. (line 6)
7275 * minor mode for structure editing: orgstruct-mode. (line 6)
7276 * minor mode for tables: orgtbl-mode. (line 6)
7277 * mode, for calc: Formula syntax for Calc.
7279 * motion commands in agenda: Agenda commands. (line 19)
7280 * motion, between headlines: Motion. (line 6)
7281 * name, of column or field: References. (line 82)
7282 * named references: References. (line 82)
7283 * names as TODO keywords: TODO types. (line 6)
7284 * narrow columns in tables: Narrow columns. (line 6)
7285 * noalign, STARTUP keyword: In-buffer settings. (line 63)
7286 * nologging, STARTUP keyword: In-buffer settings. (line 67)
7287 * nologrepeat, STARTUP keyword: In-buffer settings. (line 67)
7288 * occur, command: Sparse trees. (line 6)
7289 * odd, STARTUP keyword: In-buffer settings. (line 78)
7290 * option keyword completion: Completion. (line 6)
7291 * options, for custom agenda views: Setting Options. (line 6)
7292 * options, for customization: Customization. (line 6)
7293 * options, for export: Export options. (line 6)
7294 * options, for publishing: Publishing options. (line 6)
7295 * ordered lists: Plain lists. (line 6)
7296 * org-agenda, command: Weekly/Daily agenda. (line 9)
7297 * org-blog.el: Extensions. (line 28)
7298 * org-mode, turning on: Activation. (line 22)
7299 * org-mouse.el: Extensions. (line 16)
7300 * org-publish-project-alist: Project alist. (line 6)
7301 * org-publish.el: Extensions. (line 8)
7302 * org2rem.el: Extensions. (line 36)
7303 * orgstruct-mode: orgstruct-mode. (line 6)
7304 * orgtbl-mode <1>: Tables in arbitrary syntax.
7306 * orgtbl-mode: orgtbl-mode. (line 6)
7307 * outline tree: Headlines. (line 6)
7308 * outline-mode: Outlines. (line 6)
7309 * outlines: Outlines. (line 6)
7310 * overview, global visibility state: Visibility cycling. (line 22)
7311 * overview, STARTUP keyword: In-buffer settings. (line 56)
7312 * packages, interaction with other: Interaction. (line 6)
7313 * pasting, of subtrees: Structure editing. (line 6)
7314 * per file keywords: Per file keywords. (line 6)
7315 * plain lists: Plain lists. (line 6)
7316 * plain text external links: External links. (line 43)
7317 * presentation, of agenda items: Presentation and sorting.
7319 * printing sparse trees: Sparse trees. (line 41)
7320 * priorities: Priorities. (line 6)
7321 * priorities, of agenda items: Sorting of agenda items.
7323 * progress logging: Progress logging. (line 6)
7324 * projects, for publishing: Project alist. (line 6)
7325 * promotion, of subtrees: Structure editing. (line 6)
7326 * properties: Properties and columns.
7328 * properties, API <1>: Using the property API.
7330 * properties, API: Property API. (line 6)
7331 * properties, column view: Defining columns. (line 6)
7332 * properties, searching: Property searches. (line 6)
7333 * properties, special: Special properties. (line 6)
7334 * property syntax: Property syntax. (line 6)
7335 * publishing: Publishing. (line 6)
7336 * quoted HTML tags: Export options. (line 25)
7337 * radio tables: Radio tables. (line 6)
7338 * radio targets: Radio targets. (line 6)
7339 * range references: References. (line 60)
7340 * ranges, time: Time stamps. (line 6)
7341 * recomputing table fields: Updating the table. (line 6)
7342 * references: References. (line 6)
7343 * references, named: References. (line 82)
7344 * references, to fields: References. (line 15)
7345 * references, to ranges: References. (line 60)
7346 * region, active <1>: Export commands. (line 6)
7347 * region, active <2>: ASCII export. (line 9)
7348 * region, active <3>: Built-in table editor.
7350 * region, active: Structure editing. (line 64)
7351 * regular expressions, with tags search: Tag searches. (line 63)
7352 * remember.el <1>: Cooperation. (line 33)
7353 * remember.el: Remember. (line 6)
7354 * remote editing, from agenda: Agenda commands. (line 106)
7355 * remote editing, undo: Agenda commands. (line 107)
7356 * richer text: Enhancing text. (line 6)
7357 * RMAIL links: External links. (line 6)
7358 * SCHEDULED keyword: Deadlines and scheduling.
7360 * scheduling: Time stamps. (line 6)
7361 * Scripts, for agenda processing: Extracting Agenda Information for other programs.
7363 * search option in file links: Search options. (line 6)
7364 * search strings, custom: Custom searches. (line 6)
7365 * searching for tags: Tag searches. (line 6)
7366 * section-numbers: Export options. (line 25)
7367 * setting tags: Setting tags. (line 6)
7368 * SHELL links: External links. (line 6)
7369 * show all, command: Visibility cycling. (line 33)
7370 * show all, global visibility state: Visibility cycling. (line 22)
7371 * show hidden text: Visibility cycling. (line 6)
7372 * showall, STARTUP keyword: In-buffer settings. (line 56)
7373 * showstars, STARTUP keyword: In-buffer settings. (line 78)
7374 * sorting, of agenda items: Sorting of agenda items.
7376 * sparse tree, for deadlines: Inserting deadline/schedule.
7378 * sparse tree, for TODO: TODO basics. (line 26)
7379 * sparse tree, tag based: Tags. (line 6)
7380 * sparse trees: Sparse trees. (line 6)
7381 * special keywords: In-buffer settings. (line 6)
7382 * spreadsheet capabilities: The spreadsheet. (line 6)
7383 * statistics, for checkboxes: Checkboxes. (line 23)
7384 * storing links: Handling links. (line 9)
7385 * structure editing: Structure editing. (line 6)
7386 * structure of document: Document structure. (line 6)
7387 * sublevels, inclusion into tags match: Tag inheritance. (line 6)
7388 * sublevels, inclusion into todo list: Global TODO list. (line 34)
7389 * subscript: Subscripts and Superscripts.
7391 * subtree cycling: Visibility cycling. (line 10)
7392 * subtree visibility states: Visibility cycling. (line 10)
7393 * subtree, cut and paste: Structure editing. (line 6)
7394 * subtree, subtree visibility state: Visibility cycling. (line 10)
7395 * subtrees, cut and paste: Structure editing. (line 6)
7396 * summary: Summary. (line 6)
7397 * superscript: Subscripts and Superscripts.
7399 * syntax, of formulas: Formula syntax for Calc.
7401 * table editor, built-in: Built-in table editor.
7403 * table editor, table.el: Cooperation. (line 37)
7404 * table of contents: Export options. (line 25)
7405 * table.el: Cooperation. (line 34)
7406 * tables <1>: Export options. (line 25)
7407 * tables: Tables. (line 6)
7408 * tables, export: Enhancing text. (line 24)
7409 * tables, in other modes: Tables in arbitrary syntax.
7411 * tag completion: Completion. (line 6)
7412 * tag searches: Tag searches. (line 6)
7413 * tags: Tags. (line 6)
7414 * tags view: Matching tags and properties.
7416 * tags, setting: Setting tags. (line 6)
7417 * targets, for links: Internal links. (line 6)
7418 * targets, radio: Radio targets. (line 6)
7419 * tasks, breaking down: Breaking down tasks. (line 6)
7420 * templates, for remember: Remember templates. (line 6)
7421 * TeX interpretation: Embedded LaTeX. (line 6)
7422 * TeX macros <1>: Export options. (line 25)
7423 * TeX macros: Math symbols. (line 6)
7424 * TeX macros, export: Enhancing text. (line 21)
7425 * TeX symbol completion: Completion. (line 6)
7426 * TeX-like syntax for sub- and superscripts: Export options. (line 25)
7427 * thanks: History and Acknowledgments.
7429 * time format, custom: Custom time format. (line 6)
7430 * time grid: Time-of-day specifications.
7432 * time stamps <1>: Time stamps. (line 6)
7433 * time stamps: Timestamps. (line 6)
7434 * time, reading in minibuffer: The date/time prompt.
7436 * time-of-day specification: Time-of-day specifications.
7438 * time-sorted view: Timeline. (line 6)
7439 * timeline, single file: Timeline. (line 6)
7440 * timerange: Time stamps. (line 41)
7441 * timestamp: Time stamps. (line 14)
7442 * timestamp, inactive: Time stamps. (line 50)
7443 * timestamp, with repeater interval: Time stamps. (line 25)
7444 * timestamps, creating: Creating timestamps. (line 6)
7445 * TODO items: TODO items. (line 6)
7446 * TODO keyword matching: Global TODO list. (line 17)
7447 * TODO keyword matching, with tags search: Tag searches. (line 40)
7448 * todo keyword sets: Multiple sets in one file.
7450 * TODO keywords completion: Completion. (line 6)
7451 * TODO list, global: Global TODO list. (line 6)
7452 * TODO types: TODO types. (line 6)
7453 * TODO workflow: Workflow states. (line 6)
7454 * transient-mark-mode <1>: Export commands. (line 6)
7455 * transient-mark-mode <2>: ASCII export. (line 9)
7456 * transient-mark-mode <3>: Built-in table editor.
7458 * transient-mark-mode: Structure editing. (line 64)
7459 * translator function: Translator functions.
7461 * trees, sparse: Sparse trees. (line 6)
7462 * trees, visibility: Visibility cycling. (line 6)
7463 * tty keybindings: TTY keys. (line 6)
7464 * types as TODO keywords: TODO types. (line 6)
7465 * underlined text: Enhancing text. (line 15)
7466 * undoing remote-editing events: Agenda commands. (line 107)
7467 * updating, table: Updating the table. (line 6)
7468 * URL links: External links. (line 6)
7469 * USENET links: External links. (line 6)
7470 * variables, for customization: Customization. (line 6)
7471 * vectors, in table calculations: Formula syntax for Calc.
7473 * visibility cycling: Visibility cycling. (line 6)
7474 * visibility cycling, drawers: Drawers. (line 6)
7475 * visible text, printing: Sparse trees. (line 41)
7476 * VM links: External links. (line 6)
7477 * WANDERLUST links: External links. (line 6)
7478 * weekly agenda: Weekly/Daily agenda. (line 6)
7479 * windmove.el: Conflicts. (line 32)
7480 * workflow states as TODO keywords: Workflow states. (line 6)
7481 * XEmacs: Installation. (line 6)
7482 * XOXO export: XOXO export. (line 6)
7485 File: org, Node: Key Index, Prev: Index, Up: Top
7493 * $: Agenda commands. (line 121)
7494 * ': CDLaTeX mode. (line 43)
7495 * +: Agenda commands. (line 143)
7496 * ,: Agenda commands. (line 135)
7497 * -: Agenda commands. (line 149)
7498 * .: Agenda commands. (line 98)
7499 * :: Agenda commands. (line 129)
7500 * < <1>: The date/time prompt.
7502 * <: Using column view. (line 54)
7503 * <left>: Agenda commands. (line 95)
7504 * <RET> <1>: Agenda commands. (line 39)
7505 * <RET> <2>: The date/time prompt.
7507 * <RET> <3>: Setting tags. (line 76)
7508 * <RET>: Built-in table editor.
7510 * <right>: Agenda commands. (line 90)
7511 * <SPC> <1>: Agenda commands. (line 28)
7512 * <SPC>: Setting tags. (line 73)
7513 * <TAB> <1>: CDLaTeX mode. (line 23)
7514 * <TAB> <2>: Agenda commands. (line 33)
7515 * <TAB> <3>: Setting tags. (line 68)
7516 * <TAB> <4>: Editing and debugging formulas.
7518 * <TAB> <5>: Built-in table editor.
7520 * <TAB> <6>: Plain lists. (line 41)
7521 * <TAB>: Visibility cycling. (line 10)
7522 * > <1>: Agenda commands. (line 171)
7523 * > <2>: The date/time prompt.
7525 * >: Using column view. (line 54)
7526 * ^: CDLaTeX mode. (line 33)
7527 * _: CDLaTeX mode. (line 33)
7528 * `: CDLaTeX mode. (line 39)
7529 * a <1>: Agenda commands. (line 132)
7530 * a: Using column view. (line 43)
7531 * b: Agenda commands. (line 49)
7532 * C: Agenda commands. (line 211)
7533 * c: Agenda commands. (line 191)
7534 * C-#: Advanced features. (line 9)
7535 * C-': Agenda files. (line 18)
7536 * C-,: Agenda files. (line 18)
7537 * C-_: Agenda commands. (line 107)
7538 * C-a a L: Timeline. (line 10)
7539 * C-c ! <1>: Footnotes. (line 14)
7540 * C-c !: Creating timestamps. (line 19)
7541 * C-c #: Checkboxes. (line 56)
7542 * C-c %: Handling links. (line 81)
7543 * C-c &: Handling links. (line 85)
7544 * C-c ': Editing and debugging formulas.
7546 * C-c *: Updating the table. (line 13)
7547 * C-c +: Built-in table editor.
7549 * C-c ,: Priorities. (line 18)
7550 * C-c - <1>: Built-in table editor.
7552 * C-c -: Plain lists. (line 88)
7553 * C-c .: Creating timestamps. (line 10)
7554 * C-c /: Sparse trees. (line 15)
7555 * C-c :: Enhancing text. (line 32)
7556 * C-c ;: Comment lines. (line 10)
7557 * C-c <: Creating timestamps. (line 23)
7558 * C-c <TAB>: Built-in table editor.
7560 * C-c = <1>: Editing and debugging formulas.
7562 * C-c =: Column formulas. (line 26)
7563 * C-c >: Creating timestamps. (line 27)
7564 * C-c ?: Editing and debugging formulas.
7566 * C-c [: Agenda files. (line 12)
7567 * C-c \: Tag searches. (line 9)
7568 * C-c ]: Agenda files. (line 15)
7569 * C-c ^ <1>: Built-in table editor.
7571 * C-c ^: Structure editing. (line 52)
7572 * C-c `: Built-in table editor.
7574 * C-c a !: Stuck projects. (line 14)
7575 * C-c a #: Stuck projects. (line 13)
7576 * C-c a a: Weekly/Daily agenda. (line 9)
7577 * C-c a C: Storing searches. (line 9)
7578 * C-c a e: Exporting Agenda Views.
7580 * C-c a M: Matching tags and properties.
7582 * C-c a m: Matching tags and properties.
7584 * C-c a M: Tag searches. (line 16)
7585 * C-c a m: Tag searches. (line 12)
7586 * C-c a T: Global TODO list. (line 14)
7587 * C-c a t <1>: Global TODO list. (line 9)
7588 * C-c a t: TODO basics. (line 36)
7589 * C-c C-a: Visibility cycling. (line 33)
7590 * C-c C-b: Motion. (line 15)
7591 * C-c C-c <1>: Cooperation. (line 37)
7592 * C-c C-c <2>: The very busy C-c C-c key.
7594 * C-c C-c <3>: Processing LaTeX fragments.
7596 * C-c C-c <4>: Property syntax. (line 46)
7597 * C-c C-c <5>: Setting tags. (line 10)
7598 * C-c C-c <6>: Checkboxes. (line 37)
7599 * C-c C-c <7>: Editing and debugging formulas.
7601 * C-c C-c <8>: Built-in table editor.
7603 * C-c C-c: Plain lists. (line 81)
7604 * C-c C-d <1>: Agenda commands. (line 156)
7605 * C-c C-d: Inserting deadline/schedule.
7607 * C-c C-e: Exporting. (line 19)
7608 * C-c C-e a: ASCII export. (line 9)
7609 * C-c C-e b: Export commands. (line 7)
7610 * C-c C-e c: iCalendar export. (line 21)
7611 * C-c C-e H: Export commands. (line 10)
7612 * C-c C-e h: Export commands. (line 6)
7613 * C-c C-e I: iCalendar export. (line 16)
7614 * C-c C-e i: iCalendar export. (line 14)
7615 * C-c C-e R: Export commands. (line 13)
7616 * C-c C-e t: Export options. (line 13)
7617 * C-c C-e v <1>: XOXO export. (line 11)
7618 * C-c C-e v: Sparse trees. (line 41)
7619 * C-c C-e v a: ASCII export. (line 13)
7620 * C-c C-e v b: Export commands. (line 18)
7621 * C-c C-e v H: Export commands. (line 18)
7622 * C-c C-e v h: Export commands. (line 18)
7623 * C-c C-e v R: Export commands. (line 18)
7624 * C-c C-e x: XOXO export. (line 10)
7625 * C-c C-f: Motion. (line 12)
7626 * C-c C-j: Motion. (line 21)
7627 * C-c C-l: Handling links. (line 25)
7628 * C-c C-n: Motion. (line 8)
7629 * C-c C-o <1>: Creating timestamps. (line 31)
7630 * C-c C-o: Handling links. (line 58)
7631 * C-c C-p: Motion. (line 9)
7632 * C-c C-q <1>: Editing and debugging formulas.
7634 * C-c C-q: Built-in table editor.
7636 * C-c C-r <1>: Editing and debugging formulas.
7638 * C-c C-r: Visibility cycling. (line 34)
7639 * C-c C-s <1>: Agenda commands. (line 153)
7640 * C-c C-s: Inserting deadline/schedule.
7642 * C-c C-t <1>: Clocking work time. (line 27)
7643 * C-c C-t: TODO basics. (line 13)
7644 * C-c C-u: Motion. (line 18)
7645 * C-c C-v: TODO basics. (line 26)
7646 * C-c C-w: Inserting deadline/schedule.
7648 * C-c C-x b: Visibility cycling. (line 41)
7649 * C-c C-x C-a: ARCHIVE tag. (line 28)
7650 * C-c C-x C-b: Checkboxes. (line 38)
7651 * C-c C-x C-c <1>: Agenda commands. (line 218)
7652 * C-c C-x C-c: Using column view. (line 9)
7653 * C-c C-x C-d: Clocking work time. (line 35)
7654 * C-c C-x C-i: Clocking work time. (line 12)
7655 * C-c C-x C-k: Structure editing. (line 39)
7656 * C-c C-x C-l: Processing LaTeX fragments.
7658 * C-c C-x C-n: Handling links. (line 91)
7659 * C-c C-x C-o: Clocking work time. (line 14)
7660 * C-c C-x C-p: Handling links. (line 91)
7661 * C-c C-x C-r: Clocking work time. (line 43)
7662 * C-c C-x C-s: Moving subtrees. (line 10)
7663 * C-c C-x C-t: Custom time format. (line 12)
7664 * C-c C-x C-u: Dynamic blocks. (line 21)
7665 * C-c C-x C-w <1>: Built-in table editor.
7667 * C-c C-x C-w: Structure editing. (line 39)
7668 * C-c C-x C-x: Clocking work time. (line 31)
7669 * C-c C-x C-y <1>: Built-in table editor.
7671 * C-c C-x C-y: Structure editing. (line 46)
7672 * C-c C-x M-w <1>: Built-in table editor.
7674 * C-c C-x M-w: Structure editing. (line 43)
7675 * C-c C-y <1>: Clocking work time. (line 22)
7676 * C-c C-y: Creating timestamps. (line 48)
7677 * C-c l: Handling links. (line 9)
7678 * C-c { <1>: CDLaTeX mode. (line 21)
7679 * C-c {: Editing and debugging formulas.
7681 * C-c |: Built-in table editor.
7683 * C-c }: Editing and debugging formulas.
7685 * C-c ~: Cooperation. (line 48)
7686 * C-k: Agenda commands. (line 115)
7687 * C-S-<left>: Multiple sets in one file.
7689 * C-S-<right>: Multiple sets in one file.
7691 * C-TAB: ARCHIVE tag. (line 38)
7692 * C-u C-c *: Updating the table. (line 16)
7693 * C-u C-c .: Creating timestamps. (line 14)
7694 * C-u C-c = <1>: Editing and debugging formulas.
7696 * C-u C-c =: Field formulas. (line 24)
7697 * C-u C-c C-c: Updating the table. (line 19)
7698 * C-u C-c C-l: Handling links. (line 43)
7699 * C-u C-c C-x C-a: ARCHIVE tag. (line 31)
7700 * C-u C-c C-x C-s: Moving subtrees. (line 12)
7701 * C-u C-c C-x C-u <1>: Dynamic blocks. (line 22)
7702 * C-u C-c C-x C-u: Clocking work time. (line 70)
7703 * C-u C-u C-c *: Updating the table. (line 22)
7704 * C-u C-u C-c =: Editing and debugging formulas.
7706 * C-x C-s: Editing and debugging formulas.
7708 * C-x C-w <1>: Exporting Agenda Views.
7710 * C-x C-w: Agenda commands. (line 227)
7711 * D: Agenda commands. (line 72)
7712 * d: Agenda commands. (line 66)
7713 * e: Using column view. (line 33)
7714 * f: Agenda commands. (line 42)
7715 * g: Agenda commands. (line 76)
7716 * H: Agenda commands. (line 215)
7717 * i: Agenda commands. (line 196)
7718 * I: Agenda commands. (line 176)
7719 * l: Agenda commands. (line 55)
7720 * L: Agenda commands. (line 30)
7721 * M: Agenda commands. (line 202)
7722 * m: Agenda commands. (line 66)
7723 * M-<down> <1>: Editing and debugging formulas.
7725 * M-<down>: Built-in table editor.
7727 * M-<left> <1>: Built-in table editor.
7729 * M-<left>: Structure editing. (line 21)
7730 * M-<RET> <1>: Plain lists. (line 49)
7731 * M-<RET>: Structure editing. (line 6)
7732 * M-<right> <1>: Built-in table editor.
7734 * M-<right>: Structure editing. (line 24)
7735 * M-<TAB> <1>: Completion. (line 10)
7736 * M-<TAB> <2>: Property syntax. (line 38)
7737 * M-<TAB> <3>: Setting tags. (line 6)
7738 * M-<TAB> <4>: Per file keywords. (line 23)
7739 * M-<TAB>: Editing and debugging formulas.
7741 * M-<up> <1>: Editing and debugging formulas.
7743 * M-<up>: Built-in table editor.
7745 * M-S-<down> <1>: Editing and debugging formulas.
7747 * M-S-<down> <2>: Built-in table editor.
7749 * M-S-<down> <3>: Plain lists. (line 66)
7750 * M-S-<down>: Structure editing. (line 36)
7751 * M-S-<left> <1>: The date/time prompt.
7753 * M-S-<left> <2>: Built-in table editor.
7755 * M-S-<left> <3>: Plain lists. (line 72)
7756 * M-S-<left>: Structure editing. (line 27)
7757 * M-S-<RET> <1>: Checkboxes. (line 53)
7758 * M-S-<RET> <2>: Plain lists. (line 59)
7759 * M-S-<RET>: Structure editing. (line 18)
7760 * M-S-<right> <1>: The date/time prompt.
7762 * M-S-<right> <2>: Built-in table editor.
7764 * M-S-<right> <3>: Plain lists. (line 72)
7765 * M-S-<right>: Structure editing. (line 30)
7766 * M-S-<up> <1>: Editing and debugging formulas.
7768 * M-S-<up> <2>: Built-in table editor.
7770 * M-S-<up> <3>: Plain lists. (line 66)
7771 * M-S-<up>: Structure editing. (line 33)
7772 * mouse-1 <1>: Agenda commands. (line 33)
7773 * mouse-1 <2>: The date/time prompt.
7775 * mouse-1: Handling links. (line 72)
7776 * mouse-2 <1>: Agenda commands. (line 33)
7777 * mouse-2: Handling links. (line 72)
7778 * mouse-3 <1>: Agenda commands. (line 28)
7779 * mouse-3: Handling links. (line 77)
7780 * n <1>: Agenda commands. (line 19)
7781 * n: Using column view. (line 30)
7782 * O: Agenda commands. (line 180)
7783 * o: Agenda commands. (line 65)
7784 * P: Agenda commands. (line 140)
7785 * p <1>: Agenda commands. (line 20)
7786 * p: Using column view. (line 30)
7787 * q <1>: Agenda commands. (line 238)
7788 * q: Using column view. (line 17)
7789 * r <1>: Agenda commands. (line 80)
7790 * r: Global TODO list. (line 22)
7791 * S: Agenda commands. (line 206)
7792 * s: Agenda commands. (line 87)
7793 * S-<down> <1>: Agenda commands. (line 149)
7794 * S-<down> <2>: The date/time prompt.
7796 * S-<down> <3>: Creating timestamps. (line 40)
7797 * S-<down> <4>: Priorities. (line 23)
7798 * S-<down> <5>: Editing and debugging formulas.
7800 * S-<down>: Plain lists. (line 62)
7801 * S-<left> <1>: Agenda commands. (line 167)
7802 * S-<left> <2>: The date/time prompt.
7804 * S-<left> <3>: Creating timestamps. (line 35)
7805 * S-<left> <4>: Using column view. (line 26)
7806 * S-<left> <5>: Property syntax. (line 54)
7807 * S-<left> <6>: Multiple sets in one file.
7809 * S-<left> <7>: TODO basics. (line 20)
7810 * S-<left>: Editing and debugging formulas.
7812 * S-<RET>: Built-in table editor.
7814 * S-<right> <1>: Agenda commands. (line 159)
7815 * S-<right> <2>: The date/time prompt.
7817 * S-<right> <3>: Creating timestamps. (line 35)
7818 * S-<right> <4>: Using column view. (line 26)
7819 * S-<right> <5>: Property syntax. (line 54)
7820 * S-<right> <6>: Multiple sets in one file.
7822 * S-<right> <7>: TODO basics. (line 20)
7823 * S-<right>: Editing and debugging formulas.
7825 * S-<TAB> <1>: Built-in table editor.
7827 * S-<TAB>: Visibility cycling. (line 22)
7828 * S-<up> <1>: Agenda commands. (line 143)
7829 * S-<up> <2>: The date/time prompt.
7831 * S-<up> <3>: Creating timestamps. (line 40)
7832 * S-<up> <4>: Priorities. (line 23)
7833 * S-<up> <5>: Editing and debugging formulas.
7835 * S-<up>: Plain lists. (line 62)
7836 * S-M-<left>: Using column view. (line 58)
7837 * S-M-<RET>: TODO basics. (line 44)
7838 * S-M-<right>: Using column view. (line 55)
7839 * T: Agenda commands. (line 124)
7840 * t: Agenda commands. (line 111)
7841 * v: Using column view. (line 39)
7842 * w: Agenda commands. (line 66)
7843 * x: Agenda commands. (line 239)
7844 * X: Agenda commands. (line 183)
7845 * y: Agenda commands. (line 66)
7851 Node: Introduction
\x7f12513
7852 Node: Summary
\x7f12928
7853 Node: Installation
\x7f16080
7854 Node: Activation
\x7f17458
7855 Node: Feedback
\x7f18707
7856 Node: Document structure
\x7f20783
7857 Node: Outlines
\x7f21675
7858 Node: Headlines
\x7f22335
7859 Ref: Headlines-Footnote-1
\x7f23343
7860 Node: Visibility cycling
\x7f23442
7861 Ref: Visibility cycling-Footnote-1
\x7f25652
7862 Ref: Visibility cycling-Footnote-2
\x7f25710
7863 Ref: Visibility cycling-Footnote-3
\x7f25760
7864 Node: Motion
\x7f26030
7865 Node: Structure editing
\x7f26984
7866 Node: Archiving
\x7f29810
7867 Node: ARCHIVE tag
\x7f30368
7868 Node: Moving subtrees
\x7f32161
7869 Node: Sparse trees
\x7f33472
7870 Ref: Sparse trees-Footnote-1
\x7f35604
7871 Ref: Sparse trees-Footnote-2
\x7f35786
7872 Node: Plain lists
\x7f35901
7873 Ref: Plain lists-Footnote-1
\x7f40098
7874 Ref: Plain lists-Footnote-2
\x7f40456
7875 Node: Drawers
\x7f40637
7876 Node: orgstruct-mode
\x7f41475
7877 Node: Tables
\x7f42375
7878 Node: Built-in table editor
\x7f42956
7879 Node: Narrow columns
\x7f50195
7880 Ref: Narrow columns-Footnote-1
\x7f52130
7881 Node: Column groups
\x7f52176
7882 Node: orgtbl-mode
\x7f53709
7883 Node: The spreadsheet
\x7f54512
7884 Node: References
\x7f55599
7885 Ref: References-Footnote-1
\x7f60063
7886 Node: Formula syntax for Calc
\x7f60352
7887 Node: Formula syntax for Lisp
\x7f62809
7888 Node: Field formulas
\x7f64527
7889 Node: Column formulas
\x7f65835
7890 Node: Editing and debugging formulas
\x7f67434
7891 Node: Updating the table
\x7f71587
7892 Node: Advanced features
\x7f72622
7893 Node: Hyperlinks
\x7f77147
7894 Node: Link format
\x7f77920
7895 Node: Internal links
\x7f79213
7896 Ref: Internal links-Footnote-1
\x7f81138
7897 Node: Radio targets
\x7f81273
7898 Node: External links
\x7f81964
7899 Node: Handling links
\x7f84368
7900 Ref: Handling links-Footnote-1
\x7f89655
7901 Ref: Handling links-Footnote-2
\x7f89892
7902 Node: Link abbreviations
\x7f89966
7903 Node: Search options
\x7f91645
7904 Ref: Search options-Footnote-1
\x7f93425
7905 Node: Custom searches
\x7f93506
7906 Node: Remember
\x7f94554
7907 Node: Setting up remember
\x7f95541
7908 Node: Remember templates
\x7f96123
7909 Ref: Remember templates-Footnote-1
\x7f99569
7910 Node: Storing notes
\x7f99667
7911 Node: TODO items
\x7f101554
7912 Node: TODO basics
\x7f102531
7913 Node: TODO extensions
\x7f104295
7914 Node: Workflow states
\x7f105114
7915 Ref: Workflow states-Footnote-1
\x7f106289
7916 Node: TODO types
\x7f106382
7917 Ref: TODO types-Footnote-1
\x7f107965
7918 Node: Multiple sets in one file
\x7f108047
7919 Node: Per file keywords
\x7f109658
7920 Ref: Per file keywords-Footnote-1
\x7f110947
7921 Node: Priorities
\x7f111148
7922 Node: Breaking down tasks
\x7f112758
7923 Ref: Breaking down tasks-Footnote-1
\x7f113278
7924 Node: Checkboxes
\x7f113374
7925 Node: Tags
\x7f116129
7926 Node: Tag inheritance
\x7f116901
7927 Node: Setting tags
\x7f117838
7928 Ref: Setting tags-Footnote-1
\x7f122361
7929 Ref: Setting tags-Footnote-2
\x7f122473
7930 Node: Tag searches
\x7f122556
7931 Node: Properties and columns
\x7f125273
7932 Node: Property syntax
\x7f126378
7933 Node: Special properties
\x7f128538
7934 Node: Property searches
\x7f129454
7935 Node: Column view
\x7f130109
7936 Node: Defining columns
\x7f131277
7937 Node: Scope of column definitions
\x7f131675
7938 Node: Column attributes
\x7f132597
7939 Node: Using column view
\x7f134845
7940 Node: Property API
\x7f136832
7941 Node: Timestamps
\x7f137186
7942 Node: Time stamps
\x7f137647
7943 Ref: Time stamps-Footnote-1
\x7f140075
7944 Node: Creating timestamps
\x7f140191
7945 Node: The date/time prompt
\x7f142265
7946 Ref: The date/time prompt-Footnote-1
\x7f144253
7947 Node: Custom time format
\x7f144359
7948 Node: Deadlines and scheduling
\x7f146051
7949 Ref: Deadlines and scheduling-Footnote-1
\x7f147401
7950 Node: Inserting deadline/schedule
\x7f147556
7951 Node: Repeated tasks
\x7f148494
7952 Node: Progress logging
\x7f150133
7953 Node: Closing items
\x7f150788
7954 Ref: Closing items-Footnote-1
\x7f151722
7955 Ref: Closing items-Footnote-2
\x7f151791
7956 Node: Tracking TODO state changes
\x7f151864
7957 Node: Clocking work time
\x7f152720
7958 Ref: Clocking work time-Footnote-1
\x7f156366
7959 Ref: Clocking work time-Footnote-2
\x7f156444
7960 Node: Agenda views
\x7f156570
7961 Node: Agenda files
\x7f158521
7962 Ref: Agenda files-Footnote-1
\x7f159487
7963 Ref: Agenda files-Footnote-2
\x7f159636
7964 Node: Agenda dispatcher
\x7f159829
7965 Node: Built-in agenda views
\x7f161526
7966 Node: Weekly/Daily agenda
\x7f162106
7967 Node: Global TODO list
\x7f165048
7968 Node: Matching tags and properties
\x7f167326
7969 Node: Timeline
\x7f168415
7970 Node: Stuck projects
\x7f169087
7971 Node: Presentation and sorting
\x7f170938
7972 Node: Categories
\x7f171729
7973 Node: Time-of-day specifications
\x7f172393
7974 Node: Sorting of agenda items
\x7f174364
7975 Node: Agenda commands
\x7f175646
7976 Node: Custom agenda views
\x7f182927
7977 Node: Storing searches
\x7f183646
7978 Node: Block agenda
\x7f185558
7979 Node: Setting Options
\x7f186788
7980 Node: Exporting Agenda Views
\x7f189527
7981 Ref: Exporting Agenda Views-Footnote-1
\x7f193811
7982 Ref: Exporting Agenda Views-Footnote-2
\x7f193868
7983 Node: Extracting Agenda Information for other programs
\x7f194054
7984 Node: Embedded LaTeX
\x7f198180
7985 Ref: Embedded LaTeX-Footnote-1
\x7f199274
7986 Node: Math symbols
\x7f199464
7987 Node: Subscripts and Superscripts
\x7f200231
7988 Node: LaTeX fragments
\x7f201077
7989 Ref: LaTeX fragments-Footnote-1
\x7f203313
7990 Node: Processing LaTeX fragments
\x7f203575
7991 Node: CDLaTeX mode
\x7f204523
7992 Ref: CDLaTeX mode-Footnote-1
\x7f207009
7993 Node: Exporting
\x7f207157
7994 Node: ASCII export
\x7f208471
7995 Node: HTML export
\x7f209761
7996 Node: Export commands
\x7f210380
7997 Node: Quoting HTML tags
\x7f211624
7998 Node: Links
\x7f212254
7999 Node: Images
\x7f212951
8000 Ref: Images-Footnote-1
\x7f213822
8001 Node: CSS support
\x7f213883
8002 Ref: CSS support-Footnote-1
\x7f215202
8003 Node: XOXO export
\x7f215315
8004 Node: iCalendar export
\x7f215754
8005 Node: Text interpretation
\x7f216973
8006 Node: Comment lines
\x7f217564
8007 Node: Initial text
\x7f217959
8008 Node: Footnotes
\x7f219628
8009 Node: Enhancing text
\x7f220443
8010 Ref: Enhancing text-Footnote-1
\x7f222302
8011 Node: Export options
\x7f222392
8012 Node: Publishing
\x7f224337
8013 Ref: Publishing-Footnote-1
\x7f225133
8014 Node: Configuration
\x7f225277
8015 Node: Project alist
\x7f225995
8016 Node: Sources and destinations
\x7f227061
8017 Node: Selecting files
\x7f227791
8018 Node: Publishing action
\x7f228539
8019 Node: Publishing options
\x7f229772
8020 Node: Publishing links
\x7f231924
8021 Node: Project page index
\x7f233437
8022 Node: Sample configuration
\x7f234215
8023 Node: Simple example
\x7f234707
8024 Node: Complex example
\x7f235380
8025 Node: Triggering publication
\x7f237456
8026 Node: Miscellaneous
\x7f238141
8027 Node: Completion
\x7f238775
8028 Node: Customization
\x7f240445
8029 Node: In-buffer settings
\x7f241028
8030 Node: The very busy C-c C-c key
\x7f246367
8031 Node: Clean view
\x7f248128
8032 Node: TTY keys
\x7f250705
8033 Node: Interaction
\x7f252315
8034 Node: Cooperation
\x7f252712
8035 Node: Conflicts
\x7f255588
8036 Node: Bugs
\x7f257591
8037 Node: Extensions and Hacking
\x7f259087
8038 Node: Extensions
\x7f259758
8039 Node: Tables in arbitrary syntax
\x7f261705
8040 Node: Radio tables
\x7f262782
8041 Node: A LaTeX example
\x7f265285
8042 Ref: A LaTeX example-Footnote-1
\x7f268931
8043 Ref: A LaTeX example-Footnote-2
\x7f269079
8044 Node: Translator functions
\x7f269514
8045 Ref: Translator functions-Footnote-1
\x7f272623
8046 Node: Dynamic blocks
\x7f272711
8047 Node: Special agenda views
\x7f274683
8048 Ref: Special agenda views-Footnote-1
\x7f276993
8049 Node: Using the property API
\x7f277253
8050 Node: History and Acknowledgments
\x7f278734
8051 Node: Index
\x7f285118
8052 Node: Key Index
\x7f318864