1 This is org, produced by makeinfo version 4.7 from org.texi.
5 * Org Mode: (org). Outline-based notes management and organizer
8 This manual is for Org-mode (version 5.10).
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.10).
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:: Storing information about an entry
55 * Timestamps:: Assign date and time to items
56 * Remember:: Quickly adding nodes to the outline tree
57 * Agenda views:: Collecting information into views
58 * Embedded LaTeX:: LaTeX fragments and formulas
59 * Exporting:: Sharing and publishing of notes
60 * Publishing:: Create a web site of linked Org-mode files
61 * Miscellaneous:: All the rest which did not fit elsewhere
62 * Extensions and Hacking:: It is possible to write add-on code
63 * History and Acknowledgments:: How Org-mode came into being
64 * Index:: The fast road to specific information
65 * Key Index:: Key bindings and where they are described
67 --- The Detailed Node Listing ---
71 * Summary:: Brief summary of what Org-mode does
72 * Installation:: How to install a downloaded version of Org-mode
73 * Activation:: How to activate Org-mode for certain buffers.
74 * Feedback:: Bug reports, ideas, patches etc.
78 * Outlines:: Org-mode is based on outline-mode
79 * Headlines:: How to typeset org-tree headlines
80 * Visibility cycling:: Show and hide, much simplified
81 * Motion:: Jumping to other headlines
82 * Structure editing:: Changing sequence and level of headlines
83 * Archiving:: Move done task trees to a different place
84 * Sparse trees:: Matches embedded in context
85 * Plain lists:: Additional structure within an entry
86 * Drawers:: Tucking stuff away
87 * orgstruct-mode:: Structure editing outside Org-mode
91 * ARCHIVE tag:: Marking a tree as inactive
92 * Moving subtrees:: Moving a tree to an archive file
96 * Built-in table editor:: Simple tables
97 * Narrow columns:: Stop wasting space in tables
98 * Column groups:: Grouping to trigger vertical lines
99 * orgtbl-mode:: The table editor as minor mode
100 * The spreadsheet:: The table editor has spreadsheet capabilities.
104 * References:: How to refer to another field or range
105 * Formula syntax for Calc:: Using Calc to compute stuff
106 * Formula syntax for Lisp:: Writing formulas in Emacs Lisp
107 * Field formulas:: Formulas valid for a single field
108 * Column formulas:: Formulas valid for an entire column
109 * Editing and debugging formulas:: Fixing formulas
110 * Updating the table:: Recomputing all dependent fields
111 * Advanced features:: Field names, parameters and automatic recalc
115 * Link format:: How links in Org-mode are formatted
116 * Internal links:: Links to other places in the current file
117 * External links:: URL-like links to the world
118 * Handling links:: Creating, inserting and following
119 * Using links outside Org-mode:: Linking from my C source code?
120 * Link abbreviations:: Shortcuts for writing complex links
121 * Search options:: Linking to a specific location
122 * Custom searches:: When the default search is not enough
126 * Radio targets:: Make targets trigger links in plain text.
130 * TODO basics:: Marking and displaying TODO entries
131 * TODO extensions:: Workflow and assignments
132 * Progress logging:: Dates and notes for progress
133 * Priorities:: Some things are more important than others
134 * Breaking down tasks:: Splitting a task into manageable pieces
135 * Checkboxes:: Tick-off lists
137 Extended use of TODO keywords
139 * Workflow states:: From TODO to DONE in steps
140 * TODO types:: I do this, Fred the rest
141 * Multiple sets in one file:: Mixing it all, and still finding your way
142 * Fast access to TODO states:: Single letter selection of a state
143 * Per file keywords:: Different files, different requirements
144 * Faces for TODO keywords:: Highlighting states
148 * Closing items:: When was this entry marked DONE?
149 * Tracking TODO state changes:: When did the status change?
153 * Tag inheritance:: Tags use the tree structure of the outline
154 * Setting tags:: How to assign tags to a headline
155 * Tag searches:: Searching for combinations of tags
157 Properties and Columns
159 * Property syntax:: How properties are spelled out
160 * Special properties:: Access to other Org-mode features
161 * Property searches:: Matching property values
162 * Column view:: Tabular viewing and editing
163 * Property API:: Properties for Lisp programmers
167 * Defining columns:: The COLUMNS format property
168 * Using column view:: How to create and use column view
172 * Scope of column definitions:: Where defined, where valid?
173 * Column attributes:: Appearance and content of a column
177 * Time stamps:: Assigning a time to a tree entry
178 * Creating timestamps:: Commands which insert timestamps
179 * Deadlines and scheduling:: Planning your work
180 * Clocking work time::
184 * The date/time prompt:: How org-mode helps you entering date and time
185 * Custom time format:: Making dates look differently
187 Deadlines and Scheduling
189 * Inserting deadline/schedule:: Planning items
190 * Repeated tasks:: Items that show up again and again
194 * Setting up remember:: Some code for .emacs to get things going
195 * Remember templates:: Define the outline of different note types
196 * Storing notes:: Directly get the note to where it belongs
200 * Agenda files:: Files being searched for agenda information
201 * Agenda dispatcher:: Keyboard access to agenda views
202 * Built-in agenda views:: What is available out of the box?
203 * Presentation and sorting:: How agenda items are prepared for display
204 * Agenda commands:: Remote editing of org trees
205 * Custom agenda views:: Defining special searches and views
207 The built-in agenda views
209 * Weekly/Daily agenda:: The calendar page with current tasks
210 * Global TODO list:: All unfinished action items
211 * Matching tags and properties:: Structured information with fine-tuned search
212 * Timeline:: Time-sorted view for single file
213 * Stuck projects:: Find projects you need to review
215 Presentation and sorting
217 * Categories:: Not all tasks are equal
218 * Time-of-day specifications:: How the agenda knows the time
219 * Sorting of agenda items:: The order of things
223 * Storing searches:: Type once, use often
224 * Block agenda:: All the stuff you need in a single buffer
225 * Setting Options:: Changing the rules
226 * Exporting Agenda Views:: Writing agendas to files.
227 * Extracting Agenda Information for other programs::
231 * Math symbols:: TeX macros for symbols and Greek letters
232 * Subscripts and Superscripts:: Simple syntax for raising/lowering text
233 * LaTeX fragments:: Complex formulas made easy
234 * Processing LaTeX fragments:: Previewing LaTeX processing
235 * CDLaTeX mode:: Speed up entering of formulas
239 * ASCII export:: Exporting to plain ASCII
240 * HTML export:: Exporting to HTML
241 * LaTeX export:: Exporting to LaTeX
242 * XOXO export:: Exporting to XOXO
243 * iCalendar export:: Exporting in iCalendar format
244 * Text interpretation:: How the exporter looks at the file
248 * HTML Export commands:: How to invoke LaTeX export
249 * Quoting HTML tags:: Using direct HTML in Org-mode
250 * Links:: Transformation of links for HTML
251 * Images:: How to include images
252 * CSS support:: Changing the appearence of the output
256 * LaTeX export commands:: How to invoke LaTeX export
257 * Quoting LaTeX code:: Incorporating literal LaTeX code
259 Text interpretation by the exporter
261 * Comment lines:: Some lines will not be exported
262 * Initial text:: Text before the first headline
263 * Footnotes:: Numbers like [1]
264 * Enhancing text:: Subscripts, symbols and more
265 * Export options:: How to influence the export settings
269 * Configuration:: Defining projects
270 * Sample configuration:: Example projects
271 * Triggering publication:: Publication commands
275 * Project alist:: The central configuration variable
276 * Sources and destinations:: From here to there
277 * Selecting files:: What files are part of the project?
278 * Publishing action:: Setting the function doing the publishing
279 * Publishing options:: Tweaking HTML export
280 * Publishing links:: Which links keep working after publishing?
281 * Project page index:: Publishing a list of project files
285 * Simple example:: One-component publishing
286 * Complex example:: A multi-component publishing example
290 * Completion:: M-TAB knows what you need
291 * Customization:: Adapting Org-mode to your taste
292 * In-buffer settings:: Overview of the #+KEYWORDS
293 * The very busy C-c C-c key:: When in doubt, press C-c C-c
294 * Clean view:: Getting rid of leading stars in the outline
295 * TTY keys:: Using Org-mode on a tty
296 * Interaction:: Other Emacs packages
297 * Bugs:: Things which do not work perfectly
299 Interaction with other packages
301 * Cooperation:: Packages Org-mode cooperates with
302 * Conflicts:: Packages that lead to conflicts
304 Extensions, Hooks and Hacking
306 * Extensions:: Existing 3rd-part extensions
307 * Adding hyperlink types:: New custom link types
308 * Tables in arbitrary syntax:: Orgtbl for LaTeX and other programs
309 * Dynamic blocks:: Automatically filled blocks
310 * Special agenda views:: Customized views
311 * Using the property API:: Writing programs that use entry properties
313 Tables in arbitrary syntax
315 * Radio tables:: Sending and receiving
316 * A LaTeX example:: Step by step, almost a tutorial
317 * Translator functions:: Copy and modify
320 File: org, Node: Introduction, Next: Document structure, Prev: Top, Up: Top
327 * Summary:: Brief summary of what Org-mode does
328 * Installation:: How to install a downloaded version of Org-mode
329 * Activation:: How to activate Org-mode for certain buffers.
330 * Feedback:: Bug reports, ideas, patches etc.
333 File: org, Node: Summary, Next: Installation, Prev: Introduction, Up: Introduction
338 Org-mode is a mode for keeping notes, maintaining TODO lists, and doing
339 project planning with a fast and effective plain-text system.
341 Org-mode develops organizational tasks around NOTES files that
342 contain lists or information about projects as plain text. Org-mode is
343 implemented on top of outline-mode, which makes it possible to keep the
344 content of large files well structured. Visibility cycling and
345 structure editing help to work with the tree. Tables are easily created
346 with a built-in table editor. Org-mode supports TODO items, deadlines,
347 time stamps, and scheduling. It dynamically compiles entries into an
348 agenda that utilizes and smoothly integrates much of the Emacs calendar
349 and diary. Plain text URL-like links connect to websites, emails,
350 Usenet messages, BBDB entries, and any files related to the projects.
351 For printing and sharing of notes, an Org-mode file can be exported as a
352 structured ASCII file, as HTML, or (todo and agenda items only) as an
353 iCalendar file. It can also serve as a publishing tool for a set of
356 An important design aspect that distinguishes Org-mode from for
357 example Planner/Muse is that it encourages to store every piece of
358 information only once. In Planner, you have project pages, day pages
359 and possibly other files, duplicating some information such as tasks.
360 In Org-mode, you only have notes files. In your notes you mark entries
361 as tasks, label them with tags and timestamps. All necessary lists
362 like a schedule for the day, the agenda for a meeting, tasks lists
363 selected by tags etc are created dynamically when you need them.
365 Org-mode keeps simple things simple. When first fired up, it should
366 feel like a straightforward, easy to use outliner. Complexity is not
367 imposed, but a large amount of functionality is available when you need
368 it. Org-mode is a toolbox and can be used in different ways, for
371 * outline extension with visibility cycling and structure editing
372 * ASCII system and table editor for taking structured notes
373 * ASCII table editor with spreadsheet-like capabilities
375 * full agenda and planner with deadlines and work scheduling
376 * environment to implement David Allen's GTD system
377 * a basic database application
378 * simple hypertext system, with HTML export
379 * publishing tool to create a set of interlinked webpages
381 Org-mode's automatic, context sensitive table editor with spreadsheet
382 capabilities can be integrated into any major mode by activating the
383 minor Orgtbl-mode. Using a translation step, it can be used to maintain
384 tables in arbitrary file types, for example in LaTeX. The structure
385 editing and list creation capabilities can be used outside Org-mode with
386 the minor Orgstruct-mode.
388 There is a website for Org-mode which provides links to the newest
389 version of Org-mode, as well as additional information, frequently asked
390 questions (FAQ), links to tutorials etc. This page is located at
391 `http://orgmode.org'.
394 File: org, Node: Installation, Next: Activation, Prev: Summary, Up: Introduction
399 Important: If Org-mode is part of the Emacs distribution or an XEmacs
400 package, please skip this section and go directly to *Note Activation::.
402 If you have downloaded Org-mode from the Web, you must take the
403 following steps to install it: Go into the Org-mode distribution
404 directory and edit the top section of the file `Makefile'. You must
405 set the name of the Emacs binary (likely either `emacs' or `xemacs'),
406 and the paths to the directories where local Lisp and Info files are
407 kept. If you don't have access to the system-wide directories, create
408 your own two directories for these files, enter them into the Makefile,
409 and make sure Emacs finds the Lisp files by adding the following line
412 (setq load-path (cons "~/path/to/lispdir" load-path))
414 XEmacs users now need to install the file `noutline.el' from the
415 `xemacs' subdirectory of the Org-mode distribution. Use the command:
417 make install-noutline
419 Now byte-compile and install the Lisp files with the shell commands:
424 If you want to install the info documentation, use this command:
428 Then add to `.emacs':
430 ;; This line only if org-mode is not part of the X/Emacs distribution.
431 (require 'org-install)
434 File: org, Node: Activation, Next: Feedback, Prev: Installation, Up: Introduction
439 Add the following lines to your `.emacs' file. The last two lines
440 define _global_ keys for the commands `org-store-link' and `org-agenda'
441 - please choose suitable keys yourself.
443 ;; The following lines are always needed. Choose your own keys.
444 (add-to-list 'auto-mode-alist '("\\.org\\'" . org-mode))
445 (global-set-key "\C-cl" 'org-store-link)
446 (global-set-key "\C-ca" 'org-agenda)
448 Furthermore, you must activate `font-lock-mode' in org-mode buffers,
449 because significant functionality depends on font-locking being active.
450 You can do this with either one of the following two lines (XEmacs
451 user must use the second option):
452 (global-font-lock-mode 1) ; for all buffers
453 (add-hook 'org-mode-hook 'turn-on-font-lock) ; org-mode buffers only
455 With this setup, all files with extension `.org' will be put into
456 Org-mode. As an alternative, make the first line of a file look like
459 MY PROJECTS -*- mode: org; -*-
461 which will select Org-mode for this buffer no matter what the file's
462 name is. See also the variable `org-insert-mode-line-in-empty-file'.
465 File: org, Node: Feedback, Prev: Activation, Up: Introduction
470 If you find problems with Org-mode, or if you have questions, remarks,
471 or ideas about it, please contact the maintainer Carsten Dominik at
472 <carsten at orgmode dot org>.
474 For bug reports, please provide as much information as possible,
475 including the version information of Emacs (`C-h v emacs-version
476 <RET>') and Org-mode (`C-h v org-version <RET>'), as well as the
477 Org-mode related setup in `.emacs'. If an error occurs, a backtrace
478 can be very useful (see below on how to create one). Often a small
479 example file helps, along with clear information about:
481 1. What exactly did you do?
483 2. What did you expect to happen?
485 3. What happened instead?
486 Thank you for helping to improve this mode.
488 How to create a useful backtrace
489 ................................
491 If working with Org-mode produces an error with a message you don't
492 understand, you may have hit a bug. The best way to report this is by
493 providing, in addition to what was mentioned above, a _Backtrace_.
494 This is information from the built-in debugger about where and how the
495 error occurred. Here is how to produce a useful backtrace:
497 1. Start a fresh Emacs or XEmacs, and make sure that it will load the
498 original Lisp code in `org.el' instead of the compiled version in
499 `org.elc'. The backtrace contains much more information if it is
500 produced with uncompiled code. To do this, either rename `org.elc'
501 to something else before starting Emacs, or ask Emacs explicitly
502 to load `org.el' by using the command line
503 emacs -l /path/to/org.el
505 2. Go to the `Options' menu and select `Enter Debugger on Error'
506 (XEmacs has this option in the `Troubleshooting' sub-menu).
508 3. Do whatever you have to do to hit the error. Don't forget to
509 document the steps you take.
511 4. When you hit the error, a `*Backtrace*' buffer will appear on the
512 screen. Save this buffer to a file (for example using `C-x C-w')
513 and attach it to your bug report.
516 File: org, Node: Document structure, Next: Tables, Prev: Introduction, Up: Top
521 Org-mode is based on outline mode and provides flexible commands to
522 edit the structure of the document.
526 * Outlines:: Org-mode is based on outline-mode
527 * Headlines:: How to typeset org-tree headlines
528 * Visibility cycling:: Show and hide, much simplified
529 * Motion:: Jumping to other headlines
530 * Structure editing:: Changing sequence and level of headlines
531 * Archiving:: Move done task trees to a different place
532 * Sparse trees:: Matches embedded in context
533 * Plain lists:: Additional structure within an entry
534 * Drawers:: Tucking stuff away
535 * orgstruct-mode:: Structure editing outside Org-mode
538 File: org, Node: Outlines, Next: Headlines, Prev: Document structure, Up: Document structure
543 Org-mode is implemented on top of outline-mode. Outlines allow a
544 document to be organized in a hierarchical structure, which (at least
545 for me) is the best representation of notes and thoughts. An overview
546 of this structure is achieved by folding (hiding) large parts of the
547 document to show only the general document structure and the parts
548 currently being worked on. Org-mode greatly simplifies the use of
549 outlines by compressing the entire show/hide functionality into a single
550 command `org-cycle', which is bound to the <TAB> key.
553 File: org, Node: Headlines, Next: Visibility cycling, Prev: Outlines, Up: Document structure
558 Headlines define the structure of an outline tree. The headlines in
559 Org-mode start with one or more stars, on the left margin(1). For
569 * Another top level headline
571 Some people find the many stars too noisy and would prefer an outline
572 that has whitespace followed by a single star as headline starters.
573 *Note Clean view:: describes a setup to realize this.
575 An empty line after the end of a subtree is considered part of it and
576 will be hidden when the subtree is folded. However, if you leave at
577 least two empty lines, one empty line will remain visible after folding
578 the subtree, in order to structure the collapsed view. See the
579 variable `org-cycle-separator-lines' to modify this behavior.
581 ---------- Footnotes ----------
583 (1) See the variable `org-special-ctrl-a/e' to configure special
584 behavior of `C-a' and `C-e' in headlines.
587 File: org, Node: Visibility cycling, Next: Motion, Prev: Headlines, Up: Document structure
589 2.3 Visibility cycling
590 ======================
592 Outlines make it possible to hide parts of the text in the buffer.
593 Org-mode uses just two commands, bound to <TAB> and `S-<TAB>' to change
594 the visibility in the buffer.
597 _Subtree cycling_: Rotate current subtree among the states
599 ,-> FOLDED -> CHILDREN -> SUBTREE --.
600 '-----------------------------------'
602 The cursor must be on a headline for this to work(1). When the
603 cursor is at the beginning of the buffer and the first line is not
604 a headline, then <TAB> actually runs global cycling (see
605 below)(2). Also when called with a prefix argument (`C-u <TAB>'),
606 global cycling is invoked.
610 _Global cycling_: Rotate the entire buffer among the states
612 ,-> OVERVIEW -> CONTENTS -> SHOW ALL --.
613 '--------------------------------------'
615 When `S-<TAB>' is called with a numerical prefix N, the CONTENTS
616 view up to headlines of level N will be shown. Note that inside
617 tables, `S-<TAB>' jumps to the previous field.
623 Reveal context around point, showing the current entry, the
624 following heading and the hierarchy above. Useful for working
625 near a location exposed by a sparse tree command (*note Sparse
626 trees::) or an agenda command (*note Agenda commands::). With
627 prefix arg show, on each level, all sibling headings.
630 Show the current subtree in an indirect buffer(3). With numerical
631 prefix ARG, go up to this level and then take that tree. If ARG is
632 negative, go up that many levels. With `C-u' prefix, do not remove
633 the previously used indirect buffer.
635 When Emacs first visits an Org-mode file, the global state is set to
636 OVERVIEW, i.e. only the top level headlines are visible. This can be
637 configured through the variable `org-startup-folded', or on a per-file
638 basis by adding one of the following lines anywhere in the buffer:
644 ---------- Footnotes ----------
646 (1) see, however, the option `org-cycle-emulate-tab'.
648 (2) see the option `org-cycle-global-at-bob'.
650 (3) The indirect buffer (*note Indirect Buffers: (emacs)Indirect
651 Buffers.) will contain the entire buffer, but will be narrowed to the
652 current tree. Editing the indirect buffer will also change the
653 original buffer, but without affecting visibility in that buffer.
656 File: org, Node: Motion, Next: Structure editing, Prev: Visibility cycling, Up: Document structure
661 The following commands jump to other headlines in the buffer.
670 Next heading same level.
673 Previous heading same level.
676 Backward to higher level heading.
679 Jump to a different place without changing the current outline
680 visibility. Shows the document structure in a temporary buffer,
681 where you can use the following keys to find your destination:
682 <TAB> Cycle visibility.
683 <down> / <up> Next/previous visible headline.
684 n / p Next/previous visible headline.
685 f / b Next/previous headline same level.
688 <RET> Select this location.
691 File: org, Node: Structure editing, Next: Archiving, Prev: Motion, Up: Document structure
693 2.5 Structure editing
694 =====================
697 Insert new heading with same level as current. If the cursor is
698 in a plain list item, a new item is created (*note Plain lists::).
699 To force creation of a new headline, use a prefix arg, or first
700 press <RET> to get to the beginning of the next line. When this
701 command is used in the middle of a line, the line is split and the
702 rest of the line becomes the new headline. If the command is used
703 at the beginning of a headline, the new headline is created before
704 the current line. If at the beginning of any other line, the
705 content of that line is made the new heading. If the command is
706 used at the end of a folded subtree (i.e. behind the ellipses at
707 the end of a headline), then a headline like the current one will
708 be inserted after the end of the subtree.
711 Insert a new heading after the current subtree, same level as the
712 current headline. This command works from anywhere in the entry.
715 Insert new TODO entry with same level as current heading.
718 Promote current heading by one level.
721 Demote current heading by one level.
724 Promote the current subtree by one level.
727 Demote the current subtree by one level.
730 Move subtree up (swap with previous subtree of same level).
733 Move subtree down (swap with next subtree of same level).
737 Kill subtree, i.e. remove it from buffer but save in kill ring.
740 Copy subtree to kill ring.
743 Yank subtree from kill ring. This does modify the level of the
744 subtree to make sure the tree fits in nicely at the yank position.
745 The yank level can also be specified with a prefix arg, or by
746 yanking after a headline marker like `****'.
749 Sort same-level entries. When there is an active region, all
750 entries in the region will be sorted. Otherwise the children of
751 the current headline are sorted. The command prompts for the
752 sorting method, which can be alphabetically, numerically, by time
753 (using the first time stamp in each entry), by priority, and each
754 of these in reverse order. With a `C-u' prefix, sorting will be
755 case-sensitive. With two `C-u C-u' prefixes, duplicate entries
756 will also be removed.
758 When there is an active region (transient-mark-mode), promotion and
759 demotion work on all headlines in the region. To select a region of
760 headlines, it is best to place both point and mark at the beginning of a
761 line, mark at the beginning of the first headline, and point at the line
762 just after the last headline to change. Note that when the cursor is
763 inside a table (*note Tables::), the Meta-Cursor keys have different
767 File: org, Node: Archiving, Next: Sparse trees, Prev: Structure editing, Up: Document structure
772 When a project represented by a (sub)tree is finished, you may want to
773 move the tree out of the way and to stop it from contributing to the
774 agenda. Org-mode knows two ways of archiving. You can mark a tree with
775 the ARCHIVE tag, or you can move an entire (sub)tree to a different
780 * ARCHIVE tag:: Marking a tree as inactive
781 * Moving subtrees:: Moving a tree to an archive file
784 File: org, Node: ARCHIVE tag, Next: Moving subtrees, Prev: Archiving, Up: Archiving
786 2.6.1 The ARCHIVE tag
787 ---------------------
789 A headline that is marked with the ARCHIVE tag (*note Tags::) stays at
790 its location in the outline tree, but behaves in the following way:
791 - It does not open when you attempt to do so with a visibility
792 cycling command (*note Visibility cycling::). You can force
793 cycling archived subtrees with `C-<TAB>', or by setting the option
794 `org-cycle-open-archived-trees'. Also normal outline commands like
795 `show-all' will open archived subtrees.
797 - During sparse tree construction (*note Sparse trees::), matches in
798 archived subtrees are not exposed, unless you configure the option
799 `org-sparse-tree-open-archived-trees'.
801 - During agenda view construction (*note Agenda views::), the
802 content of archived trees is ignored unless you configure the
803 option `org-agenda-skip-archived-trees'.
805 - Archived trees are not exported (*note Exporting::), only the
806 headline is. Configure the details using the variable
807 `org-export-with-archived-trees'.
809 The following commands help managing the ARCHIVE tag:
812 Toggle the ARCHIVE tag for the current headline. When the tag is
813 set, the headline changes to a shadowish face, and the subtree
817 Check if any direct children of the current headline should be
818 archived. To do this, each subtree is checked for open TODO
819 entries. If none are found, the command offers to set the ARCHIVE
820 tag for the child. If the cursor is _not_ on a headline when this
821 command is invoked, the level 1 trees will be checked.
824 Cycle a tree even if it is tagged with ARCHIVE.
827 File: org, Node: Moving subtrees, Prev: ARCHIVE tag, Up: Archiving
829 2.6.2 Moving subtrees
830 ---------------------
832 Once an entire project is finished, you may want to move it to a
833 different location, either in the current file, or even in a different
834 file, the archive file.
837 Archive the subtree starting at the cursor position to the location
838 given by `org-archive-location'. Context information that could be
839 lost like the file name, the category, inherited tags, and the todo
840 state will be store as properties in the entry.
843 Check if any direct children of the current headline could be
844 moved to the archive. To do this, each subtree is checked for
845 open TODO entries. If none are found, the command offers to move
846 it to the archive location. If the cursor is _not_ on a headline
847 when this command is invoked, the level 1 trees will be checked.
849 The default archive location is a file in the same directory as the
850 current file, with the name derived by appending `_archive' to the
851 current file name. For information and examples on how to change this,
852 see the documentation string of the variable `org-archive-location'.
853 There is also an in-buffer option for setting this variable, for
858 If you would like to have a special ARCHIVE location for a single entry
859 or a (sub)tree, give the entry an `:ARCHIVE:' property with the
860 location as the value (*note Properties and columns::).
862 ---------- Footnotes ----------
864 (1) If there are several such lines in the buffer, each will be
865 valid for the entries below it. The first will also apply to any text
866 before it. This method is only kept for backward compatibility. The
867 preferred methods for setting multiple archive locations is using a
871 File: org, Node: Sparse trees, Next: Plain lists, Prev: Archiving, Up: Document structure
876 An important feature of Org-mode is the ability to construct _sparse
877 trees_ for selected information in an outline tree. A sparse tree
878 means that the entire document is folded as much as possible, but the
879 selected information is made visible along with the headline structure
880 above it(1). Just try it out and you will see immediately how it works.
882 Org-mode contains several commands creating such trees. The most
883 basic one is `org-occur':
886 Occur. Prompts for a regexp and shows a sparse tree with all
887 matches. If the match is in a headline, the headline is made
888 visible. If the match is in the body of an entry, headline and
889 body are made visible. In order to provide minimal context, also
890 the full hierarchy of headlines above the match is shown, as well
891 as the headline following the match. Each match is also
892 highlighted; the highlights disappear when the buffer is changed
893 by an editing command, or by pressing `C-c C-c'. When called with
894 a `C-u' prefix argument, previous highlights are kept, so several
895 calls to this command can be stacked.
896 For frequently used sparse trees of specific search strings, you can
897 use the variable `org-agenda-custom-commands' to define fast keyboard
898 access to specific sparse trees. These commands will then be
899 accessible through the agenda dispatcher (*note Agenda dispatcher::).
902 (setq org-agenda-custom-commands
903 '(("f" occur-tree "FIXME")))
905 will define the key `C-c a f' as a shortcut for creating a sparse tree
906 matching the string `FIXME'.
908 Other commands use sparse trees as well. For example `C-c C-v'
909 creates a sparse TODO tree (*note TODO basics::).
911 To print a sparse tree, you can use the Emacs command
912 `ps-print-buffer-with-faces' which does not print invisible parts of
913 the document (2). Or you can use the command `C-c C-e v' to export
914 only the visible part of the document and print the resulting file.
916 ---------- Footnotes ----------
918 (1) See also the variables `org-show-hierarchy-above',
919 `org-show-following-heading', and `org-show-siblings' for detailed
920 control on how much context is shown around each match.
922 (2) This does not work under XEmacs, because XEmacs uses selective
923 display for outlining, not text properties.
926 File: org, Node: Plain lists, Next: Drawers, Prev: Sparse trees, Up: Document structure
931 Within an entry of the outline tree, hand-formatted lists can provide
932 additional structure. They also provide a way to create lists of
933 checkboxes (*note Checkboxes::). Org-mode supports editing such lists,
934 and the HTML exporter (*note Exporting::) does parse and format them.
936 Org-mode knows ordered and unordered lists. Unordered list items
937 start with `-', `+', or `*'(1) as bullets. Ordered list items start
938 with `1.' or `1)'. Items belonging to the same list must have the same
939 indentation on the first line. In particular, if an ordered list
940 reaches number `10.', then the 2-digit numbers must be written
941 left-aligned with the other numbers in the list. Indentation also
942 determines the end of a list item. It ends before the next line that
943 is indented like the bullet/number, or less. Empty lines are part of
944 the previous item, so you can have several paragraphs in one item. If
945 you would like an empty line to terminate all currently open plain
946 lists, configure the variable `org-empty-line-terminates-plain-lists'.
950 My favorite scenes are (in this order)
951 1. The attack of the Rohirrim
952 2. Eowyns fight with the witch king
953 + this was already my favorite scene in the book
954 + I really like Miranda Otto.
955 3. Peter Jackson being shot by Legolas
957 He makes a really funny face when it happens.
958 But in the end, not individual scenes matter but the film as a whole.
960 Org-mode supports these lists by tuning filling and wrapping
961 commands to deal with them correctly(2).
963 The following commands act on items when the cursor is in the first
964 line of an item (the line with the bullet or number).
967 Items can be folded just like headline levels if you set the
968 variable `org-cycle-include-plain-lists'. The level of an item is
969 then given by the indentation of the bullet/number. Items are
970 always subordinate to real headlines, however; the hierarchies
971 remain completely separated.
973 If `org-cycle-include-plain-lists' has not been set, <TAB> fixes
974 the indentation of the curent line in a heuristic way.
977 Insert new item at current level. With prefix arg, force a new
978 heading (*note Structure editing::). If this command is used in
979 the middle of a line, the line is _split_ and the rest of the line
980 becomes the new item. If this command is executed in the
981 _whitespace before a bullet or number_, the new item is created
982 _before_ the current item. If the command is executed in the
983 white space before the text that is part of an item but does not
984 contain the bullet, a bullet is added to the current line.
987 Insert a new item with a checkbox (*note Checkboxes::).
991 Jump to the previous/next item in the current list.
995 Move the item including subitems up/down (swap with previous/next
996 item of same indentation). If the list is ordered, renumbering is
1001 Decrease/increase the indentation of the item, including subitems.
1002 Initially, the item tree is selected based on current indentation.
1003 When these commands are executed several times in direct
1004 succession, the initially selected region is used, even if the new
1005 indentation would imply a different hierarchy. To use the new
1006 hierarchy, break the command chain with a cursor motion or so.
1009 If there is a checkbox (*note Checkboxes::) in the item line,
1010 toggle the state of the checkbox. If not, make this command makes
1011 sure that all the items on this list level use the same bullet.
1012 Furthermore, if this is an ordered list, make sure the numbering
1016 Cycle the entire list level through the different itemize/enumerate
1017 bullets (`-', `+', `*', `1.', `1)'). With prefix arg, select the
1018 nth bullet from this list.
1020 ---------- Footnotes ----------
1022 (1) When using `*' as a bullet, lines must be indented or they will
1023 be seen as top-level headlines. Also, when you are hiding leading
1024 stars to get a clean outline view, plain list items starting with a
1025 star are visually indistinguishable from true headlines. In short:
1026 even though `*' is supported, it may be better not to use it for plain
1029 (2) Org-mode only changes the filling settings for Emacs. For
1030 XEmacs, you should use Kyle E. Jones' `filladapt.el'. To turn this on,
1031 put into `.emacs': `(require 'filladapt)'
1034 File: org, Node: Drawers, Next: orgstruct-mode, Prev: Plain lists, Up: Document structure
1039 Sometimes you want to keep information associated with an entry, but you
1040 normally don't want to see it. For this, Org-mode has _drawers_.
1041 Drawers need to be configured with the variable `org-drawers', and look
1044 ** This is a headline
1045 Still outside the drawer
1047 This is inside the drawer.
1051 Visibility cycling (*note Visibility cycling::) on the headline will
1052 hide and show the entry, but keep the drawer collapsed to a single line.
1053 In order to look inside the drawer, you need to move the cursor to the
1054 drawer line and press <TAB> there. Org-mode uses a drawer for storing
1055 properties (*note Properties and columns::).
1058 File: org, Node: orgstruct-mode, Prev: Drawers, Up: Document structure
1060 2.10 The Orgstruct minor mode
1061 =============================
1063 If you like the intuitive way the Org-mode structure editing and list
1064 formatting works, you might want to use these commands in other modes
1065 like text-mode or mail-mode as well. The minor mode Orgstruct-mode
1066 makes this possible. You can always toggle the mode with `M-x
1067 orgstruct-mode'. To turn it on by default, for example in mail mode,
1070 (add-hook 'mail-mode-hook 'turn-on-orgstruct)
1072 When this mode is active and the cursor is on a line that looks to
1073 Org-mode like a headline of the first line of a list item, most
1074 structure editing commands will work, even if the same keys normally
1075 have different functionality in the major mode you are using. If the
1076 cursor is not in one of those special lines, Orgstruct-mode lurks
1077 silently in the shadow.
1080 File: org, Node: Tables, Next: Hyperlinks, Prev: Document structure, Up: Top
1085 Org-mode has a very fast and intuitive table editor built-in.
1086 Spreadsheet-like calculations are supported in connection with the
1087 Emacs `calc' package.
1091 * Built-in table editor:: Simple tables
1092 * Narrow columns:: Stop wasting space in tables
1093 * Column groups:: Grouping to trigger vertical lines
1094 * orgtbl-mode:: The table editor as minor mode
1095 * The spreadsheet:: The table editor has spreadsheet capabilities.
1098 File: org, Node: Built-in table editor, Next: Narrow columns, Prev: Tables, Up: Tables
1100 3.1 The built-in table editor
1101 =============================
1103 Org-mode makes it easy to format tables in plain ASCII. Any line with
1104 `|' as the first non-whitespace character is considered part of a
1105 table. `|' is also the column separator. A table might look like this:
1107 | Name | Phone | Age |
1108 |-------+-------+-----|
1109 | Peter | 1234 | 17 |
1110 | Anna | 4321 | 25 |
1112 A table is re-aligned automatically each time you press <TAB> or
1113 <RET> or `C-c C-c' inside the table. <TAB> also moves to the next
1114 field (<RET> to the next row) and creates new table rows at the end of
1115 the table or before horizontal lines. The indentation of the table is
1116 set by the first line. Any line starting with `|-' is considered as a
1117 horizontal separator line and will be expanded on the next re-align to
1118 span the whole table width. So, to create the above table, you would
1124 and then press <TAB> to align the table and start filling in fields.
1126 When typing text into a field, Org-mode treats <DEL>, <Backspace>,
1127 and all character keys in a special way, so that inserting and deleting
1128 avoids shifting other fields. Also, when typing _immediately after the
1129 cursor was moved into a new field with `<TAB>', `S-<TAB>' or `<RET>'_,
1130 the field is automatically made blank. If this behavior is too
1131 unpredictable for you, configure the variables
1132 `org-enable-table-editor' and `org-table-auto-blank-field'.
1134 Creation and conversion
1135 .......................
1138 Convert the active region to table. If every line contains at
1139 least one TAB character, the function assumes that the material is
1140 tab separated. If every line contains a comma, comma-separated
1141 values (CSV) are assumed. If not, lines are split at whitespace
1142 into fields. You can use a prefix argument to force a specific
1143 separator: `C-u' forces CSV, `C-u C-u' forces TAB, and a numeric
1144 argument N indicates that at least N consequtive spaces, or
1145 alternatively a TAB will be the separator.
1146 If there is no active region, this command creates an empty
1147 Org-mode table. But it's easier just to start typing, like
1148 `|Name|Phone|Age <RET> |- <TAB>'.
1150 Re-aligning and field motion
1151 ............................
1154 Re-align the table without moving the cursor.
1157 Re-align the table, move to the next field. Creates a new row if
1161 Re-align, move to previous field.
1164 Re-align the table and move down to next row. Creates a new row if
1165 necessary. At the beginning or end of a line, <RET> still does
1166 NEWLINE, so it can be used to split a table.
1168 Column and row editing
1169 ......................
1173 Move the current column left/right.
1176 Kill the current column.
1179 Insert a new column to the left of the cursor position.
1183 Move the current row up/down.
1186 Kill the current row or horizontal line.
1189 Insert a new row above (with arg: below) the current row.
1192 Insert a horizontal line below current row. With prefix arg, the
1193 line is created above the current line.
1196 Sort the table lines in the region. The position of point
1197 indicates the column to be used for sorting, and the range of
1198 lines is the range between the nearest horizontal separator lines,
1199 or the entire table. If point is before the first column, you
1200 will be prompted for the sorting column. If there is an active
1201 region, the mark specifies the first line and the sorting column,
1202 while point should be in the last line to be included into the
1203 sorting. The command prompts for the sorting type
1204 (alphabetically, numerically, or by time). When called with a
1205 prefix argument, alphabetic sorting will be case-sensitive.
1211 Copy a rectangular region from a table to a special clipboard.
1212 Point and mark determine edge fields of the rectangle. The
1213 process ignores horizontal separator lines.
1216 Copy a rectangular region from a table to a special clipboard, and
1217 blank all fields in the rectangle. So this is the "cut" operation.
1220 Paste a rectangular region into a table. The upper right corner
1221 ends up in the current field. All involved fields will be
1222 overwritten. If the rectangle does not fit into the present table,
1223 the table is enlarged as needed. The process ignores horizontal
1227 Wrap several fields in a column like a paragraph. If there is an
1228 active region, and both point and mark are in the same column, the
1229 text in the column is wrapped to minimum width for the given
1230 number of lines. A prefix ARG may be used to change the number of
1231 desired lines. If there is no region, the current field is split
1232 at the cursor position and the text fragment to the right of the
1233 cursor is prepended to the field one line down. If there is no
1234 region, but you specify a prefix ARG, the current field is made
1235 blank, and the content is appended to the field above.
1241 Sum the numbers in the current column, or in the rectangle defined
1242 by the active region. The result is shown in the echo area and can
1243 be inserted with `C-y'.
1246 When current field is empty, copy from first non-empty field above.
1247 When not empty, copy current field down to next row and move cursor
1248 along with it. Depending on the variable
1249 `org-table-copy-increment', integer field values will be
1250 incremented during copy. This key is also used by CUA-mode (*note
1257 Edit the current field in a separate window. This is useful for
1258 fields that are not fully visible (*note Narrow columns::). When
1259 called with a `C-u' prefix, just make the full field visible, so
1260 that it can be edited in place.
1263 This is an alias for `C-u C-c `' to make the current field fully
1266 `M-x org-table-import'
1267 Import a file as a table. The table should be TAB- or whitespace
1268 separated. Useful, for example, to import an Excel table or data
1269 from a database, because these programs generally can write
1270 TAB-separated text files. This command works by inserting the
1271 file into the buffer and then converting the region to a table.
1272 Any prefix argument is passed on to the converter, which uses it
1273 to determine the separator.
1276 Tables can also be imported by pasting tabular text into the
1277 org-mode buffer, selecting the pasted text with `C-x C-x' and then
1278 using the `C-c |' command (see above under Creation and conversion.
1280 `M-x org-table-export'
1281 Export the table as a TAB-separated file. Useful for data
1282 exchange with, for example, Excel or database programs.
1284 If you don't like the automatic table editor because it gets in your
1285 way on lines which you would like to start with `|', you can turn it
1288 (setq org-enable-table-editor nil)
1290 Then the only table command that still works is `C-c C-c' to do a
1294 File: org, Node: Narrow columns, Next: Column groups, Prev: Built-in table editor, Up: Tables
1299 The width of columns is automatically determined by the table editor.
1300 Sometimes a single field or a few fields need to carry more text,
1301 leading to inconveniently wide columns. To limit(1) the width of a
1302 column, one field anywhere in the column may contain just the string
1303 `<N>' where `N' is an integer specifying the width of the column in
1304 characters. The next re-align will then set the width of this column
1305 to no more than this value.
1307 |---+------------------------------| |---+--------|
1309 | 1 | one | | 1 | one |
1310 | 2 | two | ----\ | 2 | two |
1311 | 3 | This is a long chunk of text | ----/ | 3 | This=> |
1312 | 4 | four | | 4 | four |
1313 |---+------------------------------| |---+--------|
1315 Fields that are wider become clipped and end in the string `=>'. Note
1316 that the full text is still in the buffer, it is only invisible. To
1317 see the full text, hold the mouse over the field - a tool-tip window
1318 will show the full content. To edit such a field, use the command `C-c
1319 `' (that is `C-c' followed by the backquote). This will open a new
1320 window with the full field. Edit it and finish with `C-c C-c'.
1322 When visiting a file containing a table with narrowed columns, the
1323 necessary character hiding has not yet happened, and the table needs to
1324 be aligned before it looks nice. Setting the option
1325 `org-startup-align-all-tables' will realign all tables in a file upon
1326 visiting, but also slow down startup. You can also set this option on
1327 a per-file basis with:
1332 ---------- Footnotes ----------
1334 (1) This feature does not work on XEmacs.
1337 File: org, Node: Column groups, Next: orgtbl-mode, Prev: Narrow columns, Up: Tables
1342 When Org-mode exports tables, it does so by default without vertical
1343 lines because that is visually more satisfying in general. Occasionally
1344 however, vertical lines can be useful to structure a table into groups
1345 of columns, much like horizontal lines can do for groups of rows. In
1346 order to specify column groups, you can use a special row where the
1347 first field contains only `/'. The further fields can either contain
1348 `<' to indicate that this column should start a group, `>' to indicate
1349 the end of a column, or `<>' to make a column a group of its own.
1350 Boundaries between colum groups will upon export be marked with
1351 vertical lines. Here is an example:
1353 | | N | N^2 | N^3 | N^4 | sqrt(n) | sqrt[4](N) |
1354 |---+----+-----+-----+-----+---------+------------|
1355 | / | <> | < | | > | < | > |
1356 | # | 1 | 1 | 1 | 1 | 1 | 1 |
1357 | # | 2 | 4 | 8 | 16 | 1.4142 | 1.1892 |
1358 | # | 3 | 9 | 27 | 81 | 1.7321 | 1.3161 |
1359 |---+----+-----+-----+-----+---------+------------|
1360 #+TBLFM: $3=$2^2::$4=$2^3::$5=$2^4::$6=sqrt($2)::$7=sqrt(sqrt(($2))
1362 It is also sufficient to just insert the colum group starters after
1363 every vertical line you'd like to have:
1365 | N | N^2 | N^3 | N^4 | sqrt(n) | sqrt[4](N) |
1366 |----+-----+-----+-----+---------+------------|
1370 File: org, Node: orgtbl-mode, Next: The spreadsheet, Prev: Column groups, Up: Tables
1372 3.4 The Orgtbl minor mode
1373 =========================
1375 If you like the intuitive way the Org-mode table editor works, you
1376 might also want to use it in other modes like text-mode or mail-mode.
1377 The minor mode Orgtbl-mode makes this possible. You can always toggle
1378 the mode with `M-x orgtbl-mode'. To turn it on by default, for example
1381 (add-hook 'mail-mode-hook 'turn-on-orgtbl)
1383 Furthermore, with some special setup, it is possible to maintain
1384 tables in arbitrary syntax with Orgtbl-mode. For example, it is
1385 possible to construct LaTeX tables with the underlying ease and power of
1386 Orgtbl-mode, including spreadsheet capabilities. For details, see
1387 *Note Tables in arbitrary syntax::.
1390 File: org, Node: The spreadsheet, Prev: orgtbl-mode, Up: Tables
1395 The table editor makes use of the Emacs `calc' package to implement
1396 spreadsheet-like capabilities. It can also evaluate Emacs Lisp forms to
1397 derive fields from other fields. While fully featured, Org-mode's
1398 implementation is not identical to other spreadsheets. For example,
1399 Org-mode knows the concept of a _column formula_ that will be applied
1400 to all non-header fields in a column without having to copy the formula
1401 to each relevant field.
1405 * References:: How to refer to another field or range
1406 * Formula syntax for Calc:: Using Calc to compute stuff
1407 * Formula syntax for Lisp:: Writing formulas in Emacs Lisp
1408 * Field formulas:: Formulas valid for a single field
1409 * Column formulas:: Formulas valid for an entire column
1410 * Editing and debugging formulas:: Fixing formulas
1411 * Updating the table:: Recomputing all dependent fields
1412 * Advanced features:: Field names, parameters and automatic recalc
1415 File: org, Node: References, Next: Formula syntax for Calc, Prev: The spreadsheet, Up: The spreadsheet
1420 To compute fields in the table from other fields, formulas must
1421 reference other fields or ranges. In Org-mode, fields can be referenced
1422 by name, by absolute coordinates, and by relative coordinates. To find
1423 out what the coordinates of a field are, press `C-c ?' in that field,
1424 or press `C-c }' to toggle the display of a grid.
1429 Formulas can reference the value of another field in two ways. Like in
1430 any other spreadsheet, you may reference fields with a letter/number
1431 combination like `B3', meaning the 2nd field in the 3rd row.
1433 Org-mode also uses another, more general operator that looks like this:
1436 Column references can be absolute like `1', `2',...`N', or relative to
1437 the current column like `+1' or `-2'.
1439 The row specification only counts data lines and ignores horizontal
1440 separator lines (hlines). You can use absolute row numbers `1'...`N',
1441 and row numbers relative to the current row like `+3' or `-1'. Or
1442 specify the row relative to one of the hlines: `I' refers to the first
1443 hline, `II' to the second etc. `-I' refers to the first such line
1444 above the current line, `+I' to the first such line below the current
1445 line. You can also write `III+2' which is the second data line after
1446 the third hline in the table. Relative row numbers like `-3' will not
1447 cross hlines if the current line is too close to the hline. Instead,
1448 the value directly at the hline is used.
1450 `0' refers to the current row and column. Also, if you omit either
1451 the column or the row part of the reference, the current row/column is
1454 Org-mode's references with _unsigned_ numbers are fixed references
1455 in the sense that if you use the same reference in the formula for two
1456 different fields, the same field will be referenced each time.
1457 Org-mode's references with _signed_ numbers are floating references
1458 because the same reference operator can reference different fields
1459 depending on the field being calculated by the formula.
1461 Here are a few examples:
1463 @2$3 2nd row, 3rd column
1465 $5 column 5 in the current row
1467 @2 current column, row 2
1468 @-1$-3 the field one row up, three columns to the left
1469 @-I$2 field just under hline above current row, column 2
1474 You may reference a rectangular range of fields by specifying two field
1475 references connected by two dots `..'. If both fields are in the
1476 current row, you may simply use `$2..$7', but if at least one field is
1477 in a different row, you need to use the general `@row$column' format at
1478 least for the first field (i.e the reference must start with `@' in
1479 order to be interpreted correctly). Examples:
1481 $1..$3 First three fields in the current row.
1482 $P..$Q Range, using column names (see under Advanced)
1483 @2$1..@4$3 6 fields between these two fields.
1484 A2..C4 Same as above.
1485 @-1$-2..@-1 3 numbers from the column to the left, 2 up to current row
1487 Range references return a vector of values that can be fed into Calc
1488 vector functions. Empty fields in ranges are normally suppressed, so
1489 that the vector contains only the non-empty fields (but see the `E'
1490 mode switch below). If there are no non-empty fields, `[0]' is
1491 returned to avoid syntax errors in formulas.
1496 `$name' is interpreted as the name of a column, parameter or constant.
1497 Constants are defined globally through the variable
1498 `org-table-formula-constants', and locally (for the file) through a
1501 #+CONSTANTS: c=299792458. pi=3.14 eps=2.4e-6
1503 Also properties (*note Properties and columns::) can be used as
1504 constants in table formulas: For a property `:XYZ:' use the name
1505 `$PROP_XYZ', and the property will be searched in the current outline
1506 entry and in the hierarchy above it. If you have the `constants.el'
1507 package, it will also be used to resolve constants, including natural
1508 constants like `$h' for Planck's constant, and units like `$km' for
1509 kilometers(1). Column names and parameters can be specified in special
1510 table lines. These are described below, see *Note Advanced features::.
1511 All names must start with a letter, and further consist of letters and
1514 ---------- Footnotes ----------
1516 (1) `Constant.el' can supply the values of constants in two
1517 different unit systems, `SI' and `cgs'. Which one is used depends on
1518 the value of the variable `constants-unit-system'. You can use the
1519 `#+STARTUP' options `constSI' and `constcgs' to set this value for the
1523 File: org, Node: Formula syntax for Calc, Next: Formula syntax for Lisp, Prev: References, Up: The spreadsheet
1525 3.5.2 Formula syntax for Calc
1526 -----------------------------
1528 A formula can be any algebraic expression understood by the Emacs
1529 `Calc' package. Note that `calc' has the non-standard convention that
1530 `/' has lower precedence than `*', so that `a/b*c' is interpreted as
1531 `a/(b*c)'. Before evaluation by `calc-eval' (*note calc-eval:
1532 (calc)Calling Calc from Your Programs.), variable substitution takes
1533 place according to the rules described above. The range vectors can be
1534 directly fed into the calc vector functions like `vmean' and `vsum'.
1536 A formula can contain an optional mode string after a semicolon.
1537 This string consists of flags to influence Calc and other modes during
1538 execution. By default, Org-mode uses the standard calc modes (precision
1539 12, angular units degrees, fraction and symbolic modes off. The display
1540 format, however, has been changed to `(float 5)' to keep tables
1541 compact. The default settings can be configured using the variable
1542 `org-calc-default-modes'.
1544 p20 switch the internal precision to 20 digits
1545 n3 s3 e2 f4 normal, scientific, engineering, or fixed display format
1546 D R angle modes: degrees, radians
1547 F S fraction and symbolic modes
1548 N interpret all fields as numbers, use 0 for non-numbers
1549 T force text interpretation
1550 E keep empty fields in ranges
1552 In addition, you may provide a `printf' format specifier to reformat
1553 the final result. A few examples:
1555 $1+$2 Sum of first and second field
1556 $1+$2;%.2f Same, format result to two decimals
1557 exp($2)+exp($1) Math functions can be used
1558 $0;%.1f Reformat current cell to 1 decimal
1559 ($3-32)*5/9 Degrees F -> C conversion
1560 $c/$1/$cm Hz -> cm conversion, using `constants.el'
1561 tan($1);Dp3s1 Compute in degrees, precision 3, display SCI 1
1562 sin($1);Dp3%.1e Same, but use printf specifier for display
1563 vmean($2..$7) Compute column range mean, using vector function
1564 vmean($2..$7);EN Same, but treat empty fields as 0
1565 taylor($3,x=7,2) taylor series of $3, at x=7, second degree
1567 Calc also contains a complete set of logical operations. For example
1569 if($1<20,teen,string("")) "teen" if age $1 less than 20, else empty
1572 File: org, Node: Formula syntax for Lisp, Next: Field formulas, Prev: Formula syntax for Calc, Up: The spreadsheet
1574 3.5.3 Emacs Lisp forms as formulas
1575 ----------------------------------
1577 It is also possible to write a formula in Emacs Lisp; this can be useful
1578 for string manipulation and control structures, if the Calc's
1579 functionality is not enough. If a formula starts with a single quote
1580 followed by an opening parenthesis, then it is evaluated as a lisp form.
1581 The evaluation should return either a string or a number. Just as with
1582 `calc' formulas, you can specify modes and a printf format after a
1583 semicolon. With Emacs Lisp forms, you need to be concious about the way
1584 field references are interpolated into the form. By default, a
1585 reference will be interpolated as a Lisp string (in double quotes)
1586 containing the field. If you provide the `N' mode switch, all
1587 referenced elements will be numbers (non-number fields will be zero) and
1588 interpolated as Lisp numbers, without quotes. If you provide the `L'
1589 flag, all fields will be interpolated literally, without quotes. I.e.,
1590 if you want a reference to be interpreted as a string by the Lisp form,
1591 enclode the reference operator itself in double quotes, like `"$3"'.
1592 Ranges are inserted as space-separated fields, so you can embed them in
1593 list or vector syntax. A few examples, note how the `N' mode is used
1594 when we do computations in lisp.
1596 Swap the first two characters of the content of column 1
1597 '(concat (substring $1 1 2) (substring $1 0 1) (substring $1 2))
1598 Add columns 1 and 2, equivalent to the Calc's `$1+$2'
1600 Compute the sum of columns 1-4, like Calc's `vsum($1..$4)'
1601 '(apply '+ '($1..$4));N
1604 File: org, Node: Field formulas, Next: Column formulas, Prev: Formula syntax for Lisp, Up: The spreadsheet
1606 3.5.4 Field formulas
1607 --------------------
1609 To assign a formula to a particular field, type it directly into the
1610 field, preceded by `:=', for example `:=$1+$2'. When you press <TAB>
1611 or <RET> or `C-c C-c' with the cursor still in the field, the formula
1612 will be stored as the formula for this field, evaluated, and the
1613 current field replaced with the result.
1615 Formulas are stored in a special line starting with `#+TBLFM:'
1616 directly below the table. If you typed the equation in the 4th field of
1617 the 3rd data line in the table, the formula will look like
1618 `@3$4=$1+$2'. When inserting/deleting/swapping column and rows with
1619 the appropriate commands, absolute references (but not relative ones)
1620 in stored formulas are modified in order to still reference the same
1621 field. Of cause this is not true if you edit the table structure with
1622 normal editing commands - then you must fix the equations yourself.
1624 Instead of typing an equation into the field, you may also use the
1628 Install a new formula for the current field. The command prompts
1629 for a formula, with default taken from the `#+TBLFM:' line, applies
1630 it to the current field and stores it.
1633 File: org, Node: Column formulas, Next: Editing and debugging formulas, Prev: Field formulas, Up: The spreadsheet
1635 3.5.5 Column formulas
1636 ---------------------
1638 Often in a table, the same formula should be used for all fields in a
1639 particular column. Instead of having to copy the formula to all fields
1640 in that column, org-mode allows to assign a single formula to an entire
1641 column. If the table contains horizontal separator hlines, everything
1642 before the first such line is considered part of the table _header_ and
1643 will not be modified by column formulas.
1645 To assign a formula to a column, type it directly into any field in
1646 the column, preceded by an equal sign, like `=$1+$2'. When you press
1647 <TAB> or <RET> or `C-c C-c' with the cursor still in the field, the
1648 formula will be stored as the formula for the current column, evaluated
1649 and the current field replaced with the result. If the field contains
1650 only `=', the previously stored formula for this column is used. For
1651 each column, Org-mode will only remember the most recently used
1652 formula. In the `TBLFM:' line, column formulas will look like
1655 Instead of typing an equation into the field, you may also use the
1659 Install a new formula for the current column and replace current
1660 field with the result of the formula. The command prompts for a
1661 formula, with default taken from the `#+TBLFM' line, applies it to
1662 the current field and stores it. With a numerical prefix (e.g.
1663 `C-5 C-c =') will apply it to that many consecutive fields in the
1667 File: org, Node: Editing and debugging formulas, Next: Updating the table, Prev: Column formulas, Up: The spreadsheet
1669 3.5.6 Editing and Debugging formulas
1670 ------------------------------------
1672 You can edit individual formulas in the minibuffer or directly in the
1673 field. Org-mode can also prepare a special buffer with all active
1674 formulas of a table. When offering a formula for editing, Org-mode
1675 converts references to the standard format (like `B3' or `D&') if
1676 possible. If you prefer to only work with the internal format (like
1677 `@3$2' or `$4'), configure the variable
1678 `org-table-use-standard-references'.
1682 Edit the formula associated with the current column/field in the
1683 minibuffer. See *Note Column formulas:: and *Note Field
1687 Re-insert the active formula (either a field formula, or a column
1688 formula) into the current field, so that you can edit it directly
1689 in the field. The advantage over editing in the minibuffer is
1690 that you can use the command `C-c ?'.
1693 While editing a formula in a table field, highlight the field(s)
1694 referenced by the reference at the cursor position in the formula.
1697 Toggle the display of row and column numbers for a table, using
1698 overlays. These are updated each time the table is aligned, you
1699 can force it with `C-c C-c'.
1702 Toggle the formula debugger on and off. See below.
1705 Edit all formulas for the current table in a special buffer, where
1706 the formulas will be displayed one per line. If the current field
1707 has an active formula, the cursor in the formula editor will mark
1708 it. While inside the special buffer, Org-mode will automatically
1709 highlight any field or range reference at the cursor position.
1710 You may edit, remove and add formulas, and use the following
1714 Exit the formula editor and store the modified formulas.
1715 With `C-u' prefix, also apply the new formulas to the entire
1719 Exit the formula editor without installing changes.
1722 Toggle all references in the formula editor between standard
1723 (like `B3') and internal (like `@3$2').
1726 Pretty-print or indent lisp formula at point. When in a line
1727 containing a lisp formula, format the formula according to
1728 Emacs Lisp rules. Another <TAB> collapses the formula back
1729 again. In the open formula, <TAB> re-indents just like in
1733 Complete Lisp symbols, just like in Emacs-lisp-mode.
1735 `S-<up>/<down>/<left>/<right>'
1736 Shift the reference at point. For example, if the reference
1737 is `B3' and you press `S-<right>', it will become `C3'. This
1738 also works for relative references, and for hline references.
1741 Move the test line for column formulas in the Org-mode buffer
1745 Scroll the window displaying the table.
1748 Turn the coordinate grid in the table on and off.
1750 Making a table field blank does not remove the formula associated
1751 with the field, because that is stored in a different line (the `TBLFM'
1752 line) - during the next recalculation the field will be filled again.
1753 To remove a formula from a field, you have to give an empty reply when
1754 prompted for the formula, or to edit the `#+TBLFM' line.
1756 You may edit the `#+TBLFM' directly and re-apply the changed
1757 equations with `C-c C-c' in that line, or with the normal recalculation
1758 commands in the table.
1763 When the evaluation of a formula leads to an error, the field content
1764 becomes the string `#ERROR'. If you would like see what is going on
1765 during variable substitution and calculation in order to find a bug,
1766 turn on formula debugging in the `Tbl' menu and repeat the calculation,
1767 for example by pressing `C-u C-u C-c = <RET>' in a field. Detailed
1768 information will be displayed.
1771 File: org, Node: Updating the table, Next: Advanced features, Prev: Editing and debugging formulas, Up: The spreadsheet
1773 3.5.7 Updating the Table
1774 ------------------------
1776 Recalculation of a table is normally not automatic, but needs to be
1777 triggered by a command. See *Note Advanced features:: for a way to make
1778 recalculation at least semi-automatically.
1780 In order to recalculate a line of a table or the entire table, use
1781 the following commands:
1784 Recalculate the current row by first applying the stored column
1785 formulas from left to right, and all field formulas in the current
1790 Recompute the entire table, line by line. Any lines before the
1791 first hline are left alone, assuming that these are part of the
1796 Iterate the table by recomputing it until no further changes occur.
1797 This may be necessary if some computed fields use the value of
1798 other fields that are computed later in the calculation sequence.
1801 File: org, Node: Advanced features, Prev: Updating the table, Up: The spreadsheet
1803 3.5.8 Advanced features
1804 -----------------------
1806 If you want the recalculation of fields to happen automatically, or if
1807 you want to be able to assign names to fields and columns, you need to
1808 reserve the first column of the table for special marking characters.
1810 Rotate the calculation mark in first column through the states `',
1811 `#', `*', `!', `$'. The meaning of these characters is discussed
1812 below. When there is an active region, change all marks in the
1815 Here is an example of a table that collects exam results of students
1816 and makes use of these features:
1818 |---+---------+--------+--------+--------+-------+------|
1819 | | Student | Prob 1 | Prob 2 | Prob 3 | Total | Note |
1820 |---+---------+--------+--------+--------+-------+------|
1821 | ! | | P1 | P2 | P3 | Tot | |
1822 | # | Maximum | 10 | 15 | 25 | 50 | 10.0 |
1823 | ^ | | m1 | m2 | m3 | mt | |
1824 |---+---------+--------+--------+--------+-------+------|
1825 | # | Peter | 10 | 8 | 23 | 41 | 8.2 |
1826 | # | Sara | 6 | 14 | 19 | 39 | 7.8 |
1827 | # | Sam | 2 | 4 | 3 | 9 | 1.8 |
1828 |---+---------+--------+--------+--------+-------+------|
1829 | | Average | | | | 29.7 | |
1830 | ^ | | | | | at | |
1831 | $ | max=50 | | | | | |
1832 |---+---------+--------+--------+--------+-------+------|
1833 #+TBLFM: $6=vsum($P1..$P3)::$7=10*$Tot/$max;%.1f::$at=vmean(@-II..@-I);%.1f
1835 Important: Please note that for these special tables, recalculating the
1836 table with `C-u C-c *' will only affect rows that are marked `#' or
1837 `*', and fields that have a formula assigned to the field itself. The
1838 column formulas are not applied in rows with empty first field.
1840 The marking characters have the following meaning:
1842 The fields in this line define names for the columns, so that you
1843 may refer to a column as `$Tot' instead of `$6'.
1846 This row defines names for the fields _above_ the row. With such
1847 a definition, any formula in the table may use `$m1' to refer to
1848 the value `10'. Also, if you assign a formula to a names field, it
1849 will be stored as `$name=...'.
1852 Similar to `^', but defines names for the fields in the row
1856 Fields in this row can define _parameters_ for formulas. For
1857 example, if a field in a `$' row contains `max=50', then formulas
1858 in this table can refer to the value 50 using `$max'. Parameters
1859 work exactly like constants, only that they can be defined on a
1863 Fields in this row are automatically recalculated when pressing
1864 <TAB> or <RET> or `S-<TAB>' in this row. Also, this row is
1865 selected for a global recalculation with `C-u C-c *'. Unmarked
1866 lines will be left alone by this command.
1869 Selects this line for global recalculation with `C-u C-c *', but
1870 not for automatic recalculation. Use this when automatic
1871 recalculation slows down editing too much.
1874 Unmarked lines are exempt from recalculation with `C-u C-c *'.
1875 All lines that should be recalculated should be marked with `#' or
1879 Do not export this line. Useful for lines that contain the
1880 narrowing `<N>' markers.
1882 Finally, just to whet your appetite on what can be done with the
1883 fantastic `calc' package, here is a table that computes the Taylor
1884 series of degree `n' at location `x' for a couple of functions
1885 (homework: try that with Excel :-)
1887 |---+-------------+---+-----+--------------------------------------|
1888 | | Func | n | x | Result |
1889 |---+-------------+---+-----+--------------------------------------|
1890 | # | exp(x) | 1 | x | 1 + x |
1891 | # | exp(x) | 2 | x | 1 + x + x^2 / 2 |
1892 | # | exp(x) | 3 | x | 1 + x + x^2 / 2 + x^3 / 6 |
1893 | # | x^2+sqrt(x) | 2 | x=0 | x*(0.5 / 0) + x^2 (2 - 0.25 / 0) / 2 |
1894 | # | x^2+sqrt(x) | 2 | x=1 | 2 + 2.5 x - 2.5 + 0.875 (x - 1)^2 |
1895 | * | tan(x) | 3 | x | 0.0175 x + 1.77e-6 x^3 |
1896 |---+-------------+---+-----+--------------------------------------|
1897 #+TBLFM: $5=taylor($2,$4,$3);n3
1900 File: org, Node: Hyperlinks, Next: TODO items, Prev: Tables, Up: Top
1905 Just like HTML, Org-mode provides links inside a file, and external
1906 links to other files, Usenet articles, emails, and much more.
1910 * Link format:: How links in Org-mode are formatted
1911 * Internal links:: Links to other places in the current file
1912 * External links:: URL-like links to the world
1913 * Handling links:: Creating, inserting and following
1914 * Using links outside Org-mode:: Linking from my C source code?
1915 * Link abbreviations:: Shortcuts for writing complex links
1916 * Search options:: Linking to a specific location
1917 * Custom searches:: When the default search is not enough
1920 File: org, Node: Link format, Next: Internal links, Prev: Hyperlinks, Up: Hyperlinks
1925 Org-mode will recognize plain URL-like links and activate them as
1926 clickable links. The general link format, however, looks like this:
1928 [[link][description]] or alternatively [[link]]
1930 Once a link in the buffer is complete (all brackets present),
1931 Org-mode will change the display so that `description' is displayed
1932 instead of `[[link][description]]' and `link' is displayed instead of
1933 `[[link]]'. Links will be highlighted in the face `org-link', which by
1934 default is an underlined face. You can directly edit the visible part
1935 of a link. Note that this can be either the `link' part (if there is
1936 no description) or the `description' part. To edit also the invisible
1937 `link' part, use `C-c C-l' with the cursor on the link.
1939 If you place the cursor at the beginning or just behind the end of
1940 the displayed text and press <BACKSPACE>, you will remove the
1941 (invisible) bracket at that location. This makes the link incomplete
1942 and the internals are again displayed as plain text. Inserting the
1943 missing bracket hides the link internals again. To show the internal
1944 structure of all links, use the menu entry `Org->Hyperlinks->Literal
1948 File: org, Node: Internal links, Next: External links, Prev: Link format, Up: Hyperlinks
1953 If the link does not look like a URL, it is considered to be internal in
1954 the current file. Links such as `[[My Target]]' or `[[My Target][Find
1955 my target]]' lead to a text search in the current file. The link can
1956 be followed with `C-c C-o' when the cursor is on the link, or with a
1957 mouse click (*note Handling links::). The preferred match for such a
1958 link is a dedicated target: the same string in double angular brackets.
1959 Targets may be located anywhere; sometimes it is convenient to put
1960 them into a comment line. For example
1964 In HTML export (*note HTML export::), such targets will become named
1965 anchors for direct access through `http' links(1).
1967 If no dedicated target exists, Org-mode will search for the words in
1968 the link. In the above example the search would be for `my target'.
1969 Links starting with a star like `*My Target' restrict the search to
1970 headlines. When searching, Org-mode will first try an exact match, but
1971 then move on to more and more lenient searches. For example, the link
1972 `[[*My Targets]]' will find any of the following:
1975 ** TODO my targets are bright
1976 ** my 20 targets are
1978 To insert a link targeting a headline, in-buffer completion can be
1979 used. Just type a star followed by a few optional letters into the
1980 buffer and press `M-<TAB>'. All headlines in the current buffer will be
1981 offered as completions. *Note Handling links::, for more commands
1984 Following a link pushes a mark onto Org-mode's own mark ring. You
1985 can return to the previous position with `C-c &'. Using this command
1986 several times in direct succession goes back to positions recorded
1991 * Radio targets:: Make targets trigger links in plain text.
1993 ---------- Footnotes ----------
1995 (1) Note that text before the first headline is usually not
1996 exported, so the first such target should be after the first headline.
1999 File: org, Node: Radio targets, Prev: Internal links, Up: Internal links
2004 Org-mode can automatically turn any occurrences of certain target names
2005 in normal text into a link. So without explicitly creating a link, the
2006 text connects to the target radioing its position. Radio targets are
2007 enclosed by triple angular brackets. For example, a target `<<<My
2008 Target>>>' causes each occurrence of `my target' in normal text to
2009 become activated as a link. The Org-mode file is scanned automatically
2010 for radio targets only when the file is first loaded into Emacs. To
2011 update the target list during editing, press `C-c C-c' with the cursor
2015 File: org, Node: External links, Next: Handling links, Prev: Internal links, Up: Hyperlinks
2020 Org-mode supports links to files, websites, Usenet and email messages,
2021 and BBDB database entries. External links are URL-like locators. They
2022 start with a short identifying string followed by a colon. There can be
2023 no space after the colon. The following list shows examples for each
2026 http://www.astro.uva.nl/~dominik on the web
2027 file:/home/dominik/images/jupiter.jpg file, absolute path
2028 file:papers/last.pdf file, relative path
2029 news:comp.emacs Usenet link
2030 mailto:adent@galaxy.net Mail link
2031 vm:folder VM folder link
2032 vm:folder#id VM message link
2033 vm://myself@some.where.org/folder#id VM on remote machine
2034 wl:folder WANDERLUST folder link
2035 wl:folder#id WANDERLUST message link
2036 mhe:folder MH-E folder link
2037 mhe:folder#id MH-E message link
2038 rmail:folder RMAIL folder link
2039 rmail:folder#id RMAIL message link
2040 gnus:group GNUS group link
2041 gnus:group#id GNUS article link
2042 bbdb:Richard Stallman BBDB link
2043 shell:ls *.org A shell command
2044 elisp:(find-file-other-frame "Elisp.org") An elisp form to evaluate
2046 A link should be enclosed in double brackets and may contain a
2047 descriptive text to be displayed instead of the url (*note Link
2048 format::), for example:
2050 [[http://www.gnu.org/software/emacs/][GNU Emacs]]
2052 If the description is a file name or URL that points to an image, HTML
2053 export (*note HTML export::) will inline the image as a clickable
2054 button. If there is no description at all and the link points to an
2055 image, that image will be inlined into the exported HTML file.
2057 Org-mode also finds external links in the normal text and activates
2058 them as links. If spaces must be part of the link (for example in
2059 `bbdb:Richard Stallman'), or if you need to remove ambiguities about
2060 the end of the link, enclose them in angular brackets.
2063 File: org, Node: Handling links, Next: Using links outside Org-mode, Prev: External links, Up: Hyperlinks
2068 Org-mode provides methods to create a link in the correct syntax, to
2069 insert it into an org-mode file, and to follow the link.
2072 Store a link to the current location. This is a _global_ command
2073 which can be used in any buffer to create a link. The link will be
2074 stored for later insertion into an Org-mode buffer (see below).
2075 For Org-mode files, if there is a `<<target>>' at the cursor, the
2076 link points to the target. Otherwise it points to the current
2077 headline. For VM, RMAIL, WANDERLUST, MH-E, GNUS and BBDB buffers,
2078 the link will indicate the current article/entry. For W3 and W3M
2079 buffers, the link goes to the current URL. For any other files,
2080 the link will point to the file, with a search string (*note
2081 Search options::) pointing to the contents of the current line.
2082 If there is an active region, the selected words will form the
2083 basis of the search string. If the automatically created link is
2084 not working correctly or accurately enough, you can write custom
2085 functions to select the search string and to do the search for
2086 particular file types - see *Note Custom searches::. The key
2087 binding `C-c l' is only a suggestion - see *Note Installation::.
2090 Insert a link. This prompts for a link to be inserted into the
2091 buffer. You can just type a link, using text for an internal
2092 link, or one of the link type prefixes mentioned in the examples
2093 above. All links stored during the current session are part of
2094 the history for this prompt, so you can access them with <up> and
2095 <down>. Completion, on the other hand, will help you to insert
2096 valid link prefixes like `http:' or `ftp:', including the prefixes
2097 defined through link abbreviations (*note Link abbreviations::).
2098 The link will be inserted into the buffer(1), along with a
2099 descriptive text. If some text was selected when this command is
2100 called, the selected text becomes the default description.
2101 Note that you don't have to use this command to insert a link.
2102 Links in Org-mode are plain text, and you can type or paste them
2103 straight into the buffer. By using this command, the links are
2104 automatically enclosed in double brackets, and you will be asked
2105 for the optional descriptive text.
2108 When `C-c C-l' is called with a `C-u' prefix argument, a link to a
2109 file will be inserted and you may use file name completion to
2110 select the name of the file. The path to the file is inserted
2111 relative to the directory of the current org file, if the linked
2112 file is in the current directory or in a subdirectory of it, or if
2113 the path is written relative to the current directory using `../'.
2114 Otherwise an absolute path is used, if possible with `~/' for
2115 your home directory. You can force an absolute path with two
2118 `C-c C-l (with cursor on existing link)'
2119 When the cursor is on an existing link, `C-c C-l' allows you to
2120 edit the link and description parts of the link.
2123 Open link at point. This will launch a web browser for URLs (using
2124 `browse-url-at-point'), run vm/mh-e/wanderlust/rmail/gnus/bbdb for
2125 the corresponding links, and execute the command in a shell link.
2126 When the cursor is on an internal link, this commands runs the
2127 corresponding search. When the cursor is on a TAG list in a
2128 headline, it creates the corresponding TAGS view. If the cursor
2129 is on a time stamp, it compiles the agenda for that date.
2130 Furthermore, it will visit text and remote files in `file:' links
2131 with Emacs and select a suitable application for local non-text
2132 files. Classification of files is based on file extension only.
2133 See option `org-file-apps'. If you want to override the default
2134 application and visit the file with Emacs, use a `C-u' prefix.
2138 On links, `mouse-2' will open the link just as `C-c C-o' would.
2139 Under Emacs 22, also `mouse-1' will follow a link.
2142 Like `mouse-2', but force file links to be opened with Emacs, and
2143 internal links to be displayed in another window(2).
2146 Push the current position onto the mark ring, to be able to return
2147 easily. Commands following an internal link do this automatically.
2150 Jump back to a recorded position. A position is recorded by the
2151 commands following internal links, and by `C-c %'. Using this
2152 command several times in direct succession moves through a ring of
2153 previously recorded positions.
2157 Move forward/backward to the next link in the buffer. At the
2158 limit of the buffer, the search fails once, and then wraps around.
2159 The key bindings for this are really too long, you might want to
2160 bind this also to `C-n' and `C-p'
2161 (add-hook 'org-load-hook
2163 (define-key 'org-mode-map "\C-n" 'org-next-link)
2164 (define-key 'org-mode-map "\C-p" 'org-previous-link)))
2166 ---------- Footnotes ----------
2168 (1) After insertion of a stored link, the link will be removed from
2169 the list of stored links. To keep it in the list later use, use a
2170 triple `C-u' prefix to `C-c C-l', or configure the option
2171 `org-keep-stored-link-after-insertion'.
2173 (2) See the variable `org-display-internal-link-with-indirect-buffer'
2176 File: org, Node: Using links outside Org-mode, Next: Link abbreviations, Prev: Handling links, Up: Hyperlinks
2178 4.5 Using links outside Org-mode
2179 ================================
2181 You can insert and follow links that have Org-mode syntax not only in
2182 Org-mode, but in any Emacs buffer. For this, you should create two
2183 global commands, like this (please select suitable global keys
2186 (global-set-key "\C-c L" 'org-insert-link-global)
2187 (global-set-key "\C-c o" 'org-open-at-point-global)
2190 File: org, Node: Link abbreviations, Next: Search options, Prev: Using links outside Org-mode, Up: Hyperlinks
2192 4.6 Link abbreviations
2193 ======================
2195 Long URLs can be cumbersome to type, and often many similar links are
2196 needed in a document. For this you can use link abbreviations. An
2197 abbreviated link looks like this
2199 [[linkword:tag][description]]
2201 where the tag is optional. Such abbreviations are resolved according to
2202 the information in the variable `org-link-abbrev-alist' that relates
2203 the linkwords to replacement text. Here is an example:
2205 (setq org-link-abbrev-alist
2206 '(("bugzilla" . "http://10.1.2.9/bugzilla/show_bug.cgi?id=")
2207 ("google" . "http://www.google.com/search?q=")
2208 ("ads" . "http://adsabs.harvard.edu/cgi-bin/
2209 nph-abs_connect?author=%s&db_key=AST")))
2211 If the replacement text contains the string `%s', it will be
2212 replaced with the tag. Otherwise the tag will be appended to the string
2213 in order to create the link. You may also specify a function that will
2214 be called with the tag as the only argument to create the link.
2216 With the above setting, you could link to a specific bug with
2217 `[[bugzilla:129]]', search the web for `OrgMode' with
2218 `[[google:OrgMode]]' and find out what the Org-mode author is doing
2219 besides Emacs hacking with `[[ads:Dominik,C]]'.
2221 If you need special abbreviations just for a single Org-mode buffer,
2222 you can define them in the file with
2224 #+LINK: bugzilla http://10.1.2.9/bugzilla/show_bug.cgi?id=
2225 #+LINK: google http://www.google.com/search?q=%s
2227 In-buffer completion *note Completion:: can be used after `[' to
2228 complete link abbreviations.
2231 File: org, Node: Search options, Next: Custom searches, Prev: Link abbreviations, Up: Hyperlinks
2233 4.7 Search options in file links
2234 ================================
2236 File links can contain additional information to make Emacs jump to a
2237 particular location in the file when following a link. This can be a
2238 line number or a search option after a double(1) colon. For example,
2239 when the command `C-c l' creates a link (*note Handling links::) to a
2240 file, it encodes the words in the current line as a search string that
2241 can be used to find this line back later when following the link with
2244 Here is the syntax of the different ways to attach a search to a file
2245 link, together with an explanation:
2247 [[file:~/code/main.c::255]]
2248 [[file:~/xx.org::My Target]]
2249 [[file:~/xx.org::*My Target]]
2250 [[file:~/xx.org::/regexp/]]
2256 Search for a link target `<<My Target>>', or do a text search for
2257 `my target', similar to the search in internal links, see *Note
2258 Internal links::. In HTML export (*note HTML export::), such a
2259 file link will become an HTML reference to the corresponding named
2260 anchor in the linked file.
2263 In an Org-mode file, restrict search to headlines.
2266 Do a regular expression search for `regexp'. This uses the Emacs
2267 command `occur' to list all matches in a separate window. If the
2268 target file is in Org-mode, `org-occur' is used to create a sparse
2269 tree with the matches.
2271 As a degenerate case, a file link with an empty file name can be used
2272 to search the current file. For example, `[[file:::find me]]' does a
2273 search for `find me' in the current file, just as `[[find me]]' would.
2275 ---------- Footnotes ----------
2277 (1) For backward compatibility, line numbers can also follow a
2281 File: org, Node: Custom searches, Prev: Search options, Up: Hyperlinks
2286 The default mechanism for creating search strings and for doing the
2287 actual search related to a file link may not work correctly in all
2288 cases. For example, BibTeX database files have many entries like
2289 `year="1993"' which would not result in good search strings, because
2290 the only unique identification for a BibTeX entry is the citation key.
2292 If you come across such a problem, you can write custom functions to
2293 set the right search string for a particular file type, and to do the
2294 search for the string in the file. Using `add-hook', these functions
2295 need to be added to the hook variables
2296 `org-create-file-search-functions' and
2297 `org-execute-file-search-functions'. See the docstring for these
2298 variables for more information. Org-mode actually uses this mechanism
2299 for BibTeX database files, and you can use the corresponding code as an
2300 implementation example. Search for `BibTeX links' in the source file.
2303 File: org, Node: TODO items, Next: Tags, Prev: Hyperlinks, Up: Top
2308 Org-mode does not maintain TODO lists as a separate document. TODO
2309 items are an integral part of the notes file, because TODO items
2310 usually come up while taking notes! With Org-mode, you simply mark any
2311 entry in a tree as being a TODO item. In this way, the information is
2312 not duplicated, and the entire context from which the item emerged is
2313 always present when you check.
2315 Of course, this technique causes TODO items to be scattered
2316 throughout your file. Org-mode provides methods to give you an
2317 overview over all things you have to do.
2321 * TODO basics:: Marking and displaying TODO entries
2322 * TODO extensions:: Workflow and assignments
2323 * Progress logging:: Dates and notes for progress
2324 * Priorities:: Some things are more important than others
2325 * Breaking down tasks:: Splitting a task into manageable pieces
2326 * Checkboxes:: Tick-off lists
2329 File: org, Node: TODO basics, Next: TODO extensions, Prev: TODO items, Up: TODO items
2331 5.1 Basic TODO functionality
2332 ============================
2334 Any headline can become a TODO item by starting it with the word TODO,
2337 *** TODO Write letter to Sam Fortune
2339 The most important commands to work with TODO entries are:
2342 Rotate the TODO state of the current item among
2344 ,-> (unmarked) -> TODO -> DONE --.
2345 '--------------------------------'
2347 The same rotation can also be done "remotely" from the timeline and
2348 agenda buffers with the `t' command key (*note Agenda commands::).
2351 Select a specific keyword using completion of (if it has been set
2352 up) the fast selection interface.
2356 Select the following/preceding TODO state, similar to cycling.
2357 Mostly useful if more than two TODO states are possible (*note
2361 Use the fast tag interface to quickly and directly select a
2362 specific TODO state. For this you need to assign keys to TODO
2364 #+SEQ_TODO: TODO(t) STARTED(s) WAITING(w) | DONE(d)
2365 See *Note Per file keywords:: and *Note Setting tags:: for more
2369 View TODO items in a _sparse tree_ (*note Sparse trees::). Folds
2370 the entire buffer, but shows all TODO items and the headings
2371 hierarchy above them. With prefix arg, search for a specific
2372 TODO. You will be prompted for the keyword, and you can also give
2373 a list of keywords like `kwd1|kwd2|...'. With numerical prefix N,
2374 show the tree for the Nth keyword in the variable
2375 `org-todo-keywords'. With two prefix args, find all TODO and DONE
2379 Show the global TODO list. This collects the TODO items from all
2380 agenda files (*note Agenda views::) into a single buffer. The
2381 buffer is in `agenda-mode', so there are commands to examine and
2382 manipulate the TODO entries directly from that buffer (*note
2383 Agenda commands::). *Note Global TODO list::, for more
2387 Insert a new TODO entry below the current one.
2390 File: org, Node: TODO extensions, Next: Progress logging, Prev: TODO basics, Up: TODO items
2392 5.2 Extended use of TODO keywords
2393 =================================
2395 The default implementation of TODO entries is just two states: TODO and
2396 DONE. You can use the TODO feature for more complicated things by
2397 configuring the variable `org-todo-keywords'. With special setup, the
2398 TODO keyword system can work differently in different files.
2400 Note that tags are another way to classify headlines in general and
2401 TODO items in particular (*note Tags::).
2405 * Workflow states:: From TODO to DONE in steps
2406 * TODO types:: I do this, Fred the rest
2407 * Multiple sets in one file:: Mixing it all, and still finding your way
2408 * Fast access to TODO states:: Single letter selection of a state
2409 * Per file keywords:: Different files, different requirements
2410 * Faces for TODO keywords:: Highlighting states
2413 File: org, Node: Workflow states, Next: TODO types, Prev: TODO extensions, Up: TODO extensions
2415 5.2.1 TODO keywords as workflow states
2416 --------------------------------------
2418 You can use TODO keywords to indicate different _sequential_ states in
2419 the process of working on an item, for example(1):
2421 (setq org-todo-keywords
2422 '((sequence "TODO" "FEEDBACK" "VERIFY" "|" "DONE" "DELEGATED")))
2424 The vertical bar separates the TODO keywords (states that _need
2425 action_) from the DONE states (which need _no further action_. If you
2426 don't provide the separator bar, the last state is used as the DONE
2427 state. With this setup, the command `C-c C-t' will cycle an entry from
2428 TODO to FEEDBACK, then to VERIFY, and finally to DONE and DELEGATED.
2429 You may also use a prefix argument to quickly select a specific state.
2430 For example `C-3 C-c C-t' will change the state immediately to VERIFY.
2431 If you define many keywords, you can use in-buffer completion (see
2432 *Note Completion::) to insert these words into the buffer. Changing a
2433 todo state can be logged with a timestamp, see *Note Tracking TODO
2434 state changes:: for more information.
2436 ---------- Footnotes ----------
2438 (1) Changing this variable only becomes effective after restarting
2439 Org-mode in a buffer.
2442 File: org, Node: TODO types, Next: Multiple sets in one file, Prev: Workflow states, Up: TODO extensions
2444 5.2.2 TODO keywords as types
2445 ----------------------------
2447 The second possibility is to use TODO keywords to indicate different
2448 _types_ of action items. For example, you might want to indicate that
2449 items are for "work" or "home". Or, when you work with several people
2450 on a single project, you might want to assign action items directly to
2451 persons, by using their names as TODO keywords. This would be set up
2454 (setq org-todo-keywords '((type "Fred" "Sara" "Lucy" "|" "DONE")))
2456 In this case, different keywords do not indicate a sequence, but
2457 rather different types. So the normal work flow would be to assign a
2458 task to a person, and later to mark it DONE. Org-mode supports this
2459 style by adapting the workings of the command `C-c C-t'(1). When used
2460 several times in succession, it will still cycle through all names, in
2461 order to first select the right type for a task. But when you return
2462 to the item after some time and execute `C-c C-t' again, it will switch
2463 from any name directly to DONE. Use prefix arguments or completion to
2464 quickly select a specific name. You can also review the items of a
2465 specific TODO type in a sparse tree by using a numeric prefix to `C-c
2466 C-v'. For example, to see all things Lucy has to do, you would use
2467 `C-3 C-c C-v'. To collect Lucy's items from all agenda files into a
2468 single buffer, you would use the prefix arg as well when creating the
2469 global todo list: `C-3 C-c t'.
2471 ---------- Footnotes ----------
2473 (1) This is also true for the `t' command in the timeline and agenda
2477 File: org, Node: Multiple sets in one file, Next: Fast access to TODO states, Prev: TODO types, Up: TODO extensions
2479 5.2.3 Multiple keyword sets in one file
2480 ---------------------------------------
2482 Sometimes you may want to use different sets of TODO keywords in
2483 parallel. For example, you may want to have the basic `TODO'/`DONE',
2484 but also a workflow for bug fixing, and a separate state indicating
2485 that an item has been canceled (so it is not DONE, but also does not
2486 require action). Your setup would then look like this:
2488 (setq org-todo-keywords
2489 '((sequence "TODO" "|" "DONE")
2490 (sequence "REPORT" "BUG" "KNOWNCAUSE" "|" "FIXED")
2491 (sequence "|" "CANCELED")))
2493 The keywords should all be different, this helps Org-mode to keep
2494 track of which subsequence should be used for a given entry. In this
2495 setup, `C-c C-t' only operates within a subsequence, so it switches from
2496 `DONE' to (nothing) to `TODO', and from `FIXED' to (nothing) to
2497 `REPORT'. Therefore you need a mechanism to initially select the
2498 correct sequence. Besides the obvious ways like typing a keyword or
2499 using completion, you may also apply the following commands:
2503 These keys jump from one TODO subset to the next. In the above
2504 example, `C-S-<right>' would jump from `TODO' or `DONE' to
2505 `REPORT', and any of the words in the second row to `CANCELED'.
2509 `S-<<left>>' and `S-<<right>>' and walk through _all_ keywords
2510 from all sets, so for example `S-<<right>>' would switch from
2511 `DONE' to `REPORT' in the example above.
2514 File: org, Node: Fast access to TODO states, Next: Per file keywords, Prev: Multiple sets in one file, Up: TODO extensions
2516 5.2.4 Fast access to TODO states
2517 --------------------------------
2519 If you would like to quickly change an entry to an arbitrary TODO state
2520 instead of cycling through the states, you can set up keys for
2521 single-letter access to the states. This is done by adding the section
2522 key after each keyword, in parenthesis. For example:
2524 (setq org-todo-keywords
2525 '((sequence "TODO(t)" "|" "DONE(d)")
2526 (sequence "REPORT(r)" "BUG(b)" "KNOWNCAUSE(k)" "|" "FIXED(f)")
2527 (sequence "|" "CANCELED(c)")))
2529 If you then press `C-u C-c C-t' followed by the selection key, the
2530 entry will be switched to this state. <SPC> can be used to remove any
2531 TODO keyword from an entry. Should you like this way of selecting TODO
2532 states a lot, you might want to set the variable
2533 `org-use-fast-todo-selection' to `t' and make this behavior the
2534 default. Check also the variable
2535 `org-fast-tag-selection-include-todo', it allows to change the TODO
2536 state through the tags interface (*note Setting tags::).
2539 File: org, Node: Per file keywords, Next: Faces for TODO keywords, Prev: Fast access to TODO states, Up: TODO extensions
2541 5.2.5 Setting up keywords for individual files
2542 ----------------------------------------------
2544 It can be very useful to use different aspects of the TODO mechanism in
2545 different files. For file-local settings, you need to add special lines
2546 to the file which set the keywords and interpretation for that file
2547 only. For example, to set one of the two examples discussed above, you
2548 need one of the following lines, starting in column zero anywhere in the
2551 #+SEQ_TODO: TODO FEEDBACK VERIFY | DONE CANCELED
2553 #+TYP_TODO: Fred Sara Lucy Mike | DONE
2555 A setup for using several sets in parallel would be:
2557 #+SEQ_TODO: TODO | DONE
2558 #+SEQ_TODO: REPORT BUG KNOWNCAUSE | FIXED
2559 #+SEQ_TODO: | CANCELED
2561 To make sure you are using the correct keyword, type `#+' into the
2562 buffer and then use `M-<TAB>' completion.
2564 Remember that the keywords after the vertical bar (or the last
2565 keyword if no bar is there) must always mean that the item is DONE
2566 (although you may use a different word). After changing one of these
2567 lines, use `C-c C-c' with the cursor still in the line to make the
2568 changes known to Org-mode(1).
2570 ---------- Footnotes ----------
2572 (1) Org-mode parses these lines only when Org-mode is activated
2573 after visiting a file. `C-c C-c' with the cursor in a line starting
2574 with `#+' is simply restarting Org-mode for the current buffer.
2577 File: org, Node: Faces for TODO keywords, Prev: Per file keywords, Up: TODO extensions
2579 5.2.6 Faces for TODO keywords
2580 -----------------------------
2582 Org-mode highlights TODO keywords with special faces: `org-todo' for
2583 keywords indicating that an item still has to be acted upon, and
2584 `org-done' for keywords indicating that an item is finished. If you
2585 are using more than 2 different states, you might want to use special
2586 faces for some of them. This can be done using the variable
2587 `org-todo-keyword-faces'. For example:
2589 (setq org-todo-keyword-faces
2590 '(("TODO" . org-warning)
2591 ("DEFERRED" . shadow)
2592 ("CANCELED" . (:foreground "blue" :weight bold))))
2595 File: org, Node: Progress logging, Next: Priorities, Prev: TODO extensions, Up: TODO items
2597 5.3 Progress Logging
2598 ====================
2600 Org-mode can automatically record a time stamp and even a note when you
2601 mark a TODO item as DONE, or even each time you change the state of a
2606 * Closing items:: When was this entry marked DONE?
2607 * Tracking TODO state changes:: When did the status change?
2610 File: org, Node: Closing items, Next: Tracking TODO state changes, Prev: Progress logging, Up: Progress logging
2615 If you want to keep track of _when_ a certain TODO item was finished,
2616 turn on logging with(1)
2618 (setq org-log-done t)
2620 Then each time you turn a TODO entry into DONE using either `C-c C-t'
2621 in the Org-mode buffer or `t' in the agenda buffer, a line `CLOSED:
2622 [timestamp]' will be inserted just after the headline. If you turn the
2623 entry back into a TODO item through further state cycling, that line
2624 will be removed again. In the timeline (*note Timeline::) and in the
2625 agenda (*note Weekly/Daily agenda::), you can then use the `l' key to
2626 display the TODO items closed on each day, giving you an overview of
2627 what has been done on a day. If you want to record a note along with
2628 the timestamp, use(2)
2630 (setq org-log-done '(done))
2632 ---------- Footnotes ----------
2634 (1) The corresponding in-buffer setting is: `#+STARTUP: logdone'
2636 (2) The corresponding in-buffer setting is: `#+STARTUP: lognotedone'
2639 File: org, Node: Tracking TODO state changes, Prev: Closing items, Up: Progress logging
2641 5.3.2 Tracking TODO state changes
2642 ---------------------------------
2644 When TODO keywords are used as workflow states (*note Workflow
2645 states::), you might want to keep track of when a state change occurred
2646 and record a note about this change. With the setting
2648 (setq org-log-done '(state))
2650 each state change will prompt you for a note that will be attached to
2651 the current headline. If you press `C-c C-c' without typing anything
2652 into the note buffer, only the time of the state change will be noted.
2653 Very likely you do not want this verbose tracking all the time, so it
2654 is probably better to configure this behavior with in-buffer options.
2655 For example, if you are tracking purchases, put these into a separate
2658 #+SEQ_TODO: TODO(t) ORDERED(o) INVOICE(i) PAYED(p) | RECEIVED(r)
2659 #+STARTUP: lognotestate
2661 If you only need to take a note for some of the states, mark those
2662 states with an additional `@', like this:
2664 #+SEQ_TODO: TODO(t) ORDERED(o@) INVOICE(i@) PAYED(p) | RECEIVED(r)
2665 #+STARTUP: lognotestate
2668 File: org, Node: Priorities, Next: Breaking down tasks, Prev: Progress logging, Up: TODO items
2673 If you use Org-mode extensively to organize your work, you may end up
2674 with a number of TODO entries so large that you'd like to prioritize
2675 them. This can be done by placing a _priority cookie_ into the
2678 *** TODO [#A] Write letter to Sam Fortune
2680 With its standard setup, Org-mode supports priorities `A', `B', and
2681 `C'. `A' is the highest priority. An entry without a cookie is
2682 treated as priority `B'. Priorities make a difference only in the
2683 agenda (*note Weekly/Daily agenda::).
2686 Set the priority of the current headline. The command prompts for
2687 a priority character `A', `B' or `C'. When you press <SPC>
2688 instead, the priority cookie is removed from the headline. The
2689 priorities can also be changed "remotely" from the timeline and
2690 agenda buffer with the `,' command (*note Agenda commands::).
2694 Increase/decrease priority of current headline(1). Note that these
2695 keys are also used to modify time stamps (*note Creating
2696 timestamps::). Furthermore, these keys are also used by CUA-mode
2697 (*note Conflicts::).
2699 You can change the range of allowed priorities by setting the
2700 variables `org-highest-priority', `org-lowest-priority', and
2701 `org-default-priority'. For an individual buffer, you may set these
2702 values (highest, lowest, default) like this (please make sure that the
2703 highest priority is earlier in the alphabet than the lowest priority):
2707 ---------- Footnotes ----------
2709 (1) See also the option `org-priority-start-cycle-with-default''.
2712 File: org, Node: Breaking down tasks, Next: Checkboxes, Prev: Priorities, Up: TODO items
2714 5.5 Breaking tasks down into subtasks
2715 =====================================
2717 It is often advisable to break down large tasks into smaller, manageable
2718 subtasks. You can do this by creating an outline tree below a TODO
2719 item, with detailed subtasks on the tree(1). Another possibility is
2720 the use of checkboxes to identify (a hierarchy of) a large number of
2721 subtasks (*note Checkboxes::).
2723 ---------- Footnotes ----------
2725 (1) To keep subtasks out of the global TODO list, see the
2726 `org-agenda-todo-list-sublevels'.
2729 File: org, Node: Checkboxes, Prev: Breaking down tasks, Up: TODO items
2734 Every item in a plain list (*note Plain lists::) can be made a checkbox
2735 by starting it with the string `[ ]'. This feature is similar to TODO
2736 items (*note TODO items::), but more lightweight. Checkboxes are not
2737 included into the global TODO list, so they are often great to split a
2738 task into a number of simple steps. Or you can use them in a shopping
2739 list. To toggle a checkbox, use `C-c C-c', or try Piotr Zielinski's
2740 `org-mouse.el'. Here is an example of a checkbox list.
2742 * TODO Organize party [3/6]
2748 - [ ] think about what music to play
2749 - [X] talk to the neighbors
2751 The `[3/6]' and `[1/3]' in the first and second line are cookies
2752 indicating how many checkboxes are present in this entry, and how many
2753 of them have been checked off. This can give you an idea on how many
2754 checkboxes remain, even without opening a folded entry. The cookies
2755 can be placed into a headline or into (the first line of) a plain list
2756 item. Each cookie covers all checkboxes structurally below that
2757 headline/item. You have to insert the cookie yourself by typing either
2758 `[/]' or `[%]'. In the first case you get an `n out of m' result, in
2759 the second case you get information about the percentage of checkboxes
2760 checked (in the above example, this would be `[50%]' and `[33%],
2763 The following commands work with checkboxes:
2766 Toggle checkbox at point. With prefix argument, set it to `[-]',
2767 which is considered to be an intermediate state.
2770 Toggle checkbox at point.
2771 - If there is an active region, toggle the first checkbox in
2772 the region and set all remaining boxes to the same status as
2773 the first. If you want to toggle all boxes in the region
2774 independently, use a prefix argument.
2776 - If the cursor is in a headline, toggle checkboxes in the
2777 region between this headline and the next (so _not_ the
2780 - If there is no active region, just toggle the checkbox at
2784 Insert a new item with a checkbox. This works only if the cursor
2785 is already in a plain list item (*note Plain lists::).
2788 Update the checkbox statistics in the current outline entry. When
2789 called with a `C-u' prefix, update the entire file. Checkbox
2790 statistic cookies are updated automatically if you toggle
2791 checkboxes with `C-c C-c' and make new ones with `M-S-<RET>'. If
2792 you delete boxes or add/change them by hand, use this command to
2793 get things back into synch. Or simply toggle any checkbox twice
2797 File: org, Node: Tags, Next: Properties and columns, Prev: TODO items, Up: Top
2802 If you wish to implement a system of labels and contexts for
2803 cross-correlating information, an excellent way is to assign tags to
2804 headlines. Org-mode has extensive support for using tags.
2806 Every headline can contain a list of tags, at the end of the
2807 headline. Tags are normal words containing letters, numbers, `_', and
2808 `@'. Tags must be preceded and followed by a single colon; like
2809 `:WORK:'. Several tags can be specified like `:WORK:URGENT:'.
2813 * Tag inheritance:: Tags use the tree structure of the outline
2814 * Setting tags:: How to assign tags to a headline
2815 * Tag searches:: Searching for combinations of tags
2818 File: org, Node: Tag inheritance, Next: Setting tags, Prev: Tags, Up: Tags
2823 Tags make use of the hierarchical structure of outline trees. If a
2824 heading has a certain tag, all subheadings will inherit the tag as
2825 well. For example, in the list
2827 * Meeting with the French group :WORK:
2828 ** Summary by Frank :BOSS:NOTES:
2829 *** TODO Prepare slides for him :ACTION:
2831 the final heading will have the tags `:WORK:', `:BOSS:', `:NOTES:', and
2832 `:ACTION:'. When executing tag searches and Org-mode finds that a
2833 certain headline matches the search criterion, it will not check any
2834 sublevel headline, assuming that these likely also match, and that the
2835 list of matches can become very long. This may not be what you want,
2836 however, and you can influence inheritance and searching using the
2837 variables `org-use-tag-inheritance' and `org-tags-match-list-sublevels'.
2840 File: org, Node: Setting tags, Next: Tag searches, Prev: Tag inheritance, Up: Tags
2845 Tags can simply be typed into the buffer at the end of a headline.
2846 After a colon, `M-<TAB>' offers completion on tags. There is also a
2847 special command for inserting tags:
2850 Enter new tags for the current headline. Org-mode will either
2851 offer completion or a special single-key interface for setting
2852 tags, see below. After pressing <RET>, the tags will be inserted
2853 and aligned to `org-tags-column'. When called with a `C-u'
2854 prefix, all tags in the current buffer will be aligned to that
2855 column, just to make things look nice. TAGS are automatically
2856 realigned after promotion, demotion, and TODO state changes (*note
2859 Org will support tag insertion based on a _list of tags_. By
2860 default this list is constructed dynamically, containing all tags
2861 currently used in the buffer. You may also globally specify a hard list
2862 of tags with the variable `org-tag-alist'. Finally you can set the
2863 default tags for a given file with lines like
2865 #+TAGS: @WORK @HOME @TENNISCLUB
2866 #+TAGS: Laptop Car PC Sailboat
2868 If you have globally defined your preferred set of tags using the
2869 variable `org-tag-alist', but would like to use a dynamic tag list in a
2870 specific file: Just add an empty TAGS option line to that file:
2874 The default support method for entering tags is minibuffer
2875 completion. However, Org-mode also implements a much better method:
2876 _fast tag selection_. This method allows to select and deselect tags
2877 with a single key per tag. To function efficiently, you should assign
2878 unique keys to most tags. This can be done globally with
2880 (setq org-tag-alist '(("@WORK" . ?w) ("@HOME" . ?h) ("Laptop" . ?l)))
2882 or on a per-file basis with
2884 #+TAGS: @WORK(w) @HOME(h) @TENNISCLUB(t) Laptop(l) PC(p)
2886 You can also group together tags that are mutually exclusive. With
2889 #+TAGS: { @WORK(w) @HOME(h) @TENNISCLUB(t) } Laptop(l) PC(p)
2891 you indicate that at most one of `@WORK', `@HOME', and `@TENNISCLUB'
2894 Don't forget to press `C-c C-c' with the cursor in one of these lines
2895 to activate any changes.
2897 If at least one tag has a selection key, pressing `C-c C-c' will
2898 automatically present you with a special interface, listing inherited
2899 tags, the tags of the current headline, and a list of all legal tags
2900 with corresponding keys(2). In this interface, you can use the
2904 Pressing keys assigned to tags will add or remove them from the
2905 list of tags in the current line. Selecting a tag in a group of
2906 mutually exclusive tags will turn off any other tags from that
2910 Enter a tag in the minibuffer, even if the tag is not in the
2911 predefined list. You will be able to complete on all tags present
2915 Clear all tags for this line.
2918 Accept the modified set.
2921 Abort without installing changes.
2924 If `q' is not assigned to a tag, it aborts like `C-g'.
2927 Turn off groups of mutually exclusive tags. Use this to (as an
2928 exception) assign several tags from such a group.
2931 Toggle auto-exit after the next change (see below). If you are
2932 using expert mode, the first `C-c' will display the selection
2935 This method lets you assign tags to a headline with very few keys. With
2936 the above setup, you could clear the current tags and set `@HOME',
2937 `Laptop' and `PC' tags with just the following keys: `C-c C-c <SPC> h l
2938 p <RET>'. Switching from `@HOME' to `@WORK' would be done with `C-c
2939 C-c w <RET>' or alternatively with `C-c C-c C-c w'. Adding the
2940 non-predefined tag `Sarah' could be done with `C-c C-c <TAB> S a r a h
2943 If you find that most of the time, you need only a single keypress to
2944 modify your list of tags, set the variable
2945 `org-fast-tag-selection-single-key'. Then you no longer have to press
2946 <RET> to exit fast tag selection - it will immediately exit after the
2947 first change. If you then occasionally need more keys, press `C-c' to
2948 turn off auto-exit for the current tag selection process (in effect:
2949 start selection with `C-c C-c C-c' instead of `C-c C-c'). If you set
2950 the variable to the value `expert', the special window is not even
2951 shown for single-key tag selection, it comes up only when you press an
2954 ---------- Footnotes ----------
2956 (1) In `org-mode-alist' use `'(:startgroup)' and `'(:endgroup)',
2957 respectively. Several groups are allowed.
2959 (2) Keys will automatically be assigned to tags which have no
2963 File: org, Node: Tag searches, Prev: Setting tags, Up: Tags
2968 Once a tags system has been set up, it can be used to collect related
2969 information into special lists.
2972 Create a sparse tree with all headlines matching a tags search.
2973 With a `C-u' prefix argument, ignore headlines that are not a TODO
2977 Create a global list of tag matches from all agenda files. *Note
2978 Matching tags and properties::.
2981 Create a global list of tag matches from all agenda files, but
2982 check only TODO items and force checking subitems (see variable
2983 `org-tags-match-list-sublevels').
2985 A tags search string can use Boolean operators `&' for AND and `|'
2986 for OR. `&' binds more strongly than `|'. Parenthesis are currently
2987 not implemented. A tag may also be preceded by `-', to select against
2988 it, and `+' is syntactic sugar for positive selection. The AND
2989 operator `&' is optional when `+' or `-' is present. Examples:
2992 Select headlines tagged `:WORK:', but discard those also tagged
2996 Selects lines tagged `:WORK:' or `:LAPTOP:'.
2999 Like before, but require the `:LAPTOP:' lines to be tagged also
3002 If you are using multi-state TODO keywords (*note TODO
3003 extensions::), it can be useful to also match on the TODO keyword.
3004 This can be done by adding a condition after a slash to a tags match.
3005 The syntax is similar to the tag matches, but should be applied with
3006 consideration: For example, a positive selection on several TODO
3007 keywords can not meaningfully be combined with boolean AND. However,
3008 _negative selection_ combined with AND can be meaningful. To make sure
3009 that only lines are checked that actually have any TODO keyword, use
3010 `C-c a M', or equivalently start the todo part after the slash with `!'.
3014 Select `:WORK:'-tagged TODO lines with the specific TODO keyword
3017 `WORK/!-WAITING-NEXT'
3018 Select `:WORK:'-tagged TODO lines that are neither `WAITING' nor
3021 `WORK/+WAITING|+NEXT'
3022 Select `:WORK:'-tagged TODO lines that are either `WAITING' or
3025 Any element of the tag/todo match can be a regular expression - in
3026 this case it must be enclosed in curly braces. For example,
3027 `WORK+{^BOSS.*}' matches headlines that contain the tag `WORK' and any
3028 tag starting with `BOSS'.
3030 You can also require a headline to be of a certain level, by writing
3031 instead of any TAG an expression like `LEVEL=3'. For example, a search
3032 `+LEVEL=3+BOSS/-DONE' lists all level three headlines that have the tag
3033 BOSS and are _not_ marked with the todo keyword DONE.
3036 File: org, Node: Properties and columns, Next: Timestamps, Prev: Tags, Up: Top
3038 7 Properties and Columns
3039 ************************
3041 Properties are a set of key-value pairs associated with an entry. There
3042 are two main applications for properties in Org-mode. First, properties
3043 are like tags, but with a value. For example, in a file where you
3044 document bugs and plan releases of a piece of software, instead of using
3045 tags like `:release_1:', `:release_2:', it can be more efficient to use
3046 a property `RELEASE' with a value `1.0' or `2.0'. Second, you can use
3047 properties to implement (very basic) database capabilities in an
3048 Org-mode buffer, for example to create a list of Music CD's you own.
3049 You can edit and view properties conveniently in column view (*note
3054 * Property syntax:: How properties are spelled out
3055 * Special properties:: Access to other Org-mode features
3056 * Property searches:: Matching property values
3057 * Column view:: Tabular viewing and editing
3058 * Property API:: Properties for Lisp programmers
3061 File: org, Node: Property syntax, Next: Special properties, Prev: Properties and columns, Up: Properties and columns
3066 Properties are key-value pairs. They need to be inserted into a special
3067 drawer (*note Drawers::) with the name `PROPERTIES'. Each property is
3068 specified on a single line, with the key (surrounded by colons) first,
3069 and the value after it. Here is an example:
3073 *** Goldberg Variations
3075 :Title: Goldberg Variations
3076 :Composer: J.S. Bach
3078 :Publisher: Deutsche Grammphon
3082 You may define the allowed values for a particular property `XYZ' by
3083 setting a property `XYZ_ALL'. This special property is _inherited_, so
3084 if you set it in a level 1 entry, it will apply to the entire tree.
3085 When allowed values are defined, setting the corresponding property
3086 becomes easier and is less prone to typing errors. For the example
3087 with the CD collection, we can predefine publishers and the number of
3088 disks in a box like this:
3092 :NDisks_ALL: 1 2 3 4
3093 :Publisher_ALL: "Deutsche Grammophon" Phillips EMI
3096 If you want to set properties that can be inherited by any entry in a
3097 file, use a line like
3099 #+PROPERTY: NDisks_ALL 1 2 3 4
3101 Property values set with the global variable `org-global-properties'
3102 can be inherited by all entries in all Org-mode files.
3104 The following commands help to work with properties:
3107 After an initial colon in a line, complete property keys. All
3108 keys used in the current file will be offered as possible
3111 `M-x org-insert-property-drawer'
3112 Insert a property drawer into the current entry. The drawer will
3113 be inserted early in the entry, but after the lines with planning
3114 information like deadlines.
3117 With the cursor in a property drawer, this executes property
3121 Set a property in the current entry. Both the property and the
3122 value can be inserted using completion.
3125 Switch property at point to the next/previous allowed value.
3128 Remove a property from the current entry.
3131 Globally remove a property, from all entries in the current file.
3134 File: org, Node: Special properties, Next: Property searches, Prev: Property syntax, Up: Properties and columns
3136 7.2 Special Properties
3137 ======================
3139 Special properties provide alternative access method to Org-mode
3140 features discussed in the previous chapters, like the TODO state or the
3141 priority of an entry. This interface exists so that you can include
3142 these states into columns view (*note Column view::). The following
3143 property names are special and should not be used as keys in the
3146 TODO The TODO keyword of the entry.
3147 TAGS The tags defined directly in the headline.
3148 ALLTAGS All tags, including inherited ones.
3149 PRIORITY The priority of the entry, a string with a single letter.
3150 DEADLINE The deadline time string, without the angular brackets.
3151 SCHEDULED The scheduling time stamp, without the angular brackets.
3154 File: org, Node: Property searches, Next: Column view, Prev: Special properties, Up: Properties and columns
3156 7.3 Property searches
3157 =====================
3159 To create sparse trees and special lists with selection based on
3160 properties, the same commands are used as for tag searches (*note Tag
3161 searches::), and the same logic applies. For example, a search string
3163 +WORK-BOSS+PRIORITY="A"+coffee="unlimited"+with={Sarah\|Denny}
3165 finds entries tagged `:WORK:' but not `:BOSS:', which also have a
3166 priority value `A', a `:coffee:' property with the value `unlimited',
3167 and a `:with:' property that is matched by the regular expression
3171 File: org, Node: Column view, Next: Property API, Prev: Property searches, Up: Properties and columns
3176 A great way to view and edit properties in an outline tree is _column
3177 view_. In column view, each outline item is turned into a table row.
3178 Columns in this table provide access to properties of the entries.
3179 Org-mode implements columns by overlaying a tabular structure over the
3180 headline of each item. While the headlines have been turned into a
3181 table row, you can still change the visibility of the outline tree.
3182 For example, you get a compact table by switching to CONTENTS view
3183 (`S-<TAB> S-<TAB>', or simply `c' while column view is active), but you
3184 can still open, read, and edit the entry below each headline. Or, you
3185 can switch to column view after executing a sparse tree command and in
3186 this way get a table only for the selected items. Column view also
3187 works in agenda buffers (*note Agenda views::) where queries have
3188 collected selected items, possibly from a number of files.
3192 * Defining columns:: The COLUMNS format property
3193 * Using column view:: How to create and use column view
3196 File: org, Node: Defining columns, Next: Using column view, Prev: Column view, Up: Column view
3198 7.4.1 Defining Columns
3199 ----------------------
3201 Setting up a column view first requires defining the columns. This is
3202 done by defining a column format line.
3206 * Scope of column definitions:: Where defined, where valid?
3207 * Column attributes:: Appearance and content of a column
3210 File: org, Node: Scope of column definitions, Next: Column attributes, Prev: Defining columns, Up: Defining columns
3212 7.4.1.1 Scope of column definitions
3213 ...................................
3215 To define a column format for an entire file, use a line like
3217 #+COLUMNS: %25ITEM %TAGS %PRIORITY %TODO
3219 To specify a format that only applies to a specific tree, add a
3220 COLUMNS property to the top node of that tree, for example
3221 ** Top node for columns view
3223 :COLUMNS: %25ITEM %TAGS %PRIORITY %TODO
3226 If a `COLUMNS' property is present in an entry, it defines columns
3227 for the entry itself, and for the entire subtree below it. Since the
3228 column definition is part of the hierarchical structure of the document,
3229 you can define columns on level 1 that are general enough for all
3230 sublevels, and more specific columns further down, when you edit a
3231 deeper part of the tree.
3234 File: org, Node: Column attributes, Prev: Scope of column definitions, Up: Defining columns
3236 7.4.1.2 Column attributes
3237 .........................
3239 A column definition sets the attributes of a column. The general
3240 definition looks like this:
3242 %[width]property[(title)][{summary-type}]
3244 Except for the percent sign and the property name, all items are
3245 optional. The individual parts have the following meaning:
3247 width An integer specifying the width of the column in characters.
3248 If omitted, the width will be determined automatically.
3249 property The property that should be edited in this column.
3250 (title) The header text for the column. If omitted, the
3251 property name is used.
3252 {summary-type} The summary type. If specified, the column values for
3253 parent nodes are computed from the children.
3254 Supported summary types are:
3255 {+} Sum numbers in this column.
3256 {:} Sum times, HH:MM:SS, plain numbers are hours.
3257 {X} Checkbox status, [X] if all children are [X].
3259 Here is an example for a complete columns definition, along with allowed
3262 :COLUMNS: %20ITEM %9Approved(Approved?){X} %Owner %11Status %10Time_Spent{:}
3263 :Owner_ALL: Tammy Mark Karl Lisa Don
3264 :Status_ALL: "In progress" "Not started yet" "Finished" ""
3265 :Approved_ALL: "[ ]" "[X]"
3267 The first column, `%25ITEM', means the first 25 characters of the
3268 item itself, i.e. of the headline. You probably always should start the
3269 column definition with the ITEM specifier. The other specifiers create
3270 columns `Owner' with a list of names as allowed values, for `Status'
3271 with four different possible values, and for a checkbox field
3272 `Approved'. When no width is given after the `%' character, the column
3273 will be exactly as wide as it needs to be in order to fully display all
3274 values. The `Approved' column does have a modified title (`Approved?',
3275 with a question mark). Summaries will be created for the `Time_Spent'
3276 column by adding time duration expressions like HH:MM, and for the
3277 `Approved' column, by providing an `[X]' status if all children have
3281 File: org, Node: Using column view, Prev: Defining columns, Up: Column view
3283 7.4.2 Using Column View
3284 -----------------------
3286 Turning column view on and off
3287 ..............................
3290 Create the column view for the local environment. This command
3291 searches the hierarchy, up from point, for a `COLUMNS' property
3292 that defines a format. When one is found, the column view table
3293 is established for the entire tree, starting from the entry that
3294 contains the `COLUMNS' property. If none is found, the format is
3295 taken from the `#+COLUMNS' line or from the variable
3296 `org-columns-default-format', and column view is established for
3297 the current entry and its subtree.
3305 `<left> <right> <up> <down>'
3306 Move through the column view from field to field.
3309 Switch to the next/previous allowed value of the field. For this,
3310 you have to have specified allowed values for a property.
3313 Same as `S-<left>/<right>'
3316 Edit the property at point. For the special properties, this will
3317 invoke the same interface that you normally use to change that
3318 property. For example, when editing a TAGS property, the tag
3319 completion or fast selection interface will pop up.
3322 View the full value of this property. This is useful if the width
3323 of the column is smaller than that of the value.
3326 Edit the list of allowed values for this property. If the list is
3327 found in the hierarchy, the modified values is stored there. If
3328 no list is found, the new value is stored in the first entry that
3329 is part of the current column view.
3331 Modifying the table structure
3332 .............................
3335 Make the column narrower/wider by one character.
3338 Insert a new column, to the right of the current column.
3341 Delete the current column.
3344 File: org, Node: Property API, Prev: Column view, Up: Properties and columns
3346 7.5 The Property API
3347 ====================
3349 There is a full API for accessing and changing properties. This API can
3350 be used by Emacs Lisp programs to work with properties and to implement
3351 features based on them. For more information see *Note Using the
3355 File: org, Node: Timestamps, Next: Remember, Prev: Properties and columns, Up: Top
3360 Items can be labeled with timestamps to make them useful for project
3365 * Time stamps:: Assigning a time to a tree entry
3366 * Creating timestamps:: Commands which insert timestamps
3367 * Deadlines and scheduling:: Planning your work
3368 * Clocking work time::
3371 File: org, Node: Time stamps, Next: Creating timestamps, Prev: Timestamps, Up: Timestamps
3373 8.1 Time stamps, deadlines and scheduling
3374 =========================================
3376 A time stamp is a specification of a date (possibly with time or a range
3377 of times) in a special format, either `<2003-09-16 Tue>' or
3378 `<2003-09-16 Tue 09:39>' or `<2003-09-16 Tue 12:00-12:30>'(1). A time
3379 stamp can appear anywhere in the headline or body of an org-tree entry.
3380 Its presence causes entries to be shown on specific dates in the agenda
3381 (*note Weekly/Daily agenda::). We distinguish:
3383 PLAIN TIME STAMP, EVENT, APPOINTMENT
3384 A simple time stamp just assigns a date/time to an item. This is
3385 just like writing down an appointment or event in a paper agenda.
3386 In the timeline and agenda displays, the headline of an entry
3387 associated with a plain time stamp will be shown exactly on that
3390 * Meet Peter at the movies <2006-11-01 Wed 19:15>
3391 * Discussion on climate change <2006-11-02 Thu 20:00-22:00>
3393 TIME STAMP WITH REPEATER INTERVAL
3394 A time stamp may contain a _repeater interval_, indicating that it
3395 applies not only on the given date, but again and again after a
3396 certain interval of N days (d), weeks (w), months(m), or years(y).
3397 The following will show up in the agenda every Wednesday:
3399 * Pick up Sam at school <2007-05-16 Wed 12:30 +1w>
3401 DIARY-STYLE SEXP ENTRIES
3402 For more complex date specifications, Org-mode supports using the
3403 special sexp diary entries implemented in the Emacs calendar/diary
3404 package. For example
3406 * The nerd meeting on every 2nd Thursday of the month
3407 <%%(diary-float t 4 2)>
3410 Two time stamps connected by `--' denote a range. The headline
3411 will be shown on the first and last day of the range, and on any
3412 dates that are displayed and fall in the range. Here is an
3415 ** Meeting in Amsterdam
3416 <2004-08-23 Mon>--<2004-08-26 Thu>
3419 Just like a plain time stamp, but with square brackets instead of
3420 angular ones. These time stamps are inactive in the sense that
3421 they do _not_ trigger an entry to show up in the agenda.
3423 * Gillian comes late for the fifth time [2006-11-01 Wed]
3426 ---------- Footnotes ----------
3428 (1) This is the standard ISO date/time format. If you cannot get
3429 used to these, see *Note Custom time format::
3432 File: org, Node: Creating timestamps, Next: Deadlines and scheduling, Prev: Time stamps, Up: Timestamps
3434 8.2 Creating timestamps
3435 =======================
3437 For Org-mode to recognize time stamps, they need to be in the specific
3438 format. All commands listed below produce time stamps in the correct
3442 Prompt for a date and insert a corresponding time stamp. When the
3443 cursor is at a previously used time stamp, it is updated to NOW.
3444 When this command is used twice in succession, a time range is
3448 Like `C-c .', but use the alternative format which contains date
3449 and time. The default time can be rounded to multiples of 5
3450 minutes, see the option `org-time-stamp-rounding-minutes'.
3453 Like `C-c .', but insert an inactive time stamp that will not cause
3457 Insert a time stamp corresponding to the cursor date in the
3461 Access the Emacs calendar for the current date. If there is a
3462 timestamp in the current line, goto the corresponding date instead.
3465 Access the agenda for the date given by the time stamp or -range at
3466 point (*note Weekly/Daily agenda::).
3470 Change date at cursor by one day. These key bindings conflict with
3471 CUA-mode (*note Conflicts::).
3475 Change the item under the cursor in a timestamp. The cursor can
3476 be on a year, month, day, hour or minute. Note that if the cursor
3477 is in a headline and not at a time stamp, these same keys modify
3478 the priority of an item. (*note Priorities::). The key bindings
3479 also conflict with CUA-mode (*note Conflicts::).
3482 Evaluate a time range by computing the difference between start and
3483 end. With prefix arg, insert result after the time range (in a
3484 table: into the following column).
3488 * The date/time prompt:: How org-mode helps you entering date and time
3489 * Custom time format:: Making dates look differently
3492 File: org, Node: The date/time prompt, Next: Custom time format, Prev: Creating timestamps, Up: Creating timestamps
3494 8.2.1 The date/time prompt
3495 --------------------------
3497 When Org-mode prompts for a date/time, the prompt suggests to enter an
3498 ISO date. But it will in fact accept any string containing some date
3499 and/or time information. You can, for example, use `C-y' to paste a
3500 (possibly multi-line) string copied from an email message. Org-mode
3501 will find whatever information is in there and will replace anything not
3502 specified with the current date and time. For example:
3504 3-2-5 --> 2003-02-05
3505 feb 15 --> currentyear-02-15
3506 sep 12 9 --> 2009-09-12
3507 12:45 --> today 12:45
3508 22 sept 0:34 --> currentyear-09-22 0:34
3509 12 --> currentyear-currentmonth-12
3510 Fri --> nearest Friday (today or later)
3511 +4 --> 4 days from now (if +N is the only thing given)
3513 The function understands English month and weekday abbreviations. If
3514 you want to use unabbreviated names and/or other languages, configure
3515 the variables `parse-time-months' and `parse-time-weekdays'.
3517 Parallel to the minibuffer prompt, a calendar is popped up(1). When
3518 you exit the date prompt, either by clicking on a date in the calendar,
3519 or by pressing <RET>, the date selected in the calendar will be
3520 combined with the information entered at the prompt. You can control
3521 the calendar fully from the minibuffer:
3524 Scroll calendar backwards by one month.
3527 Scroll calendar forwards by one month.
3530 Select date by clicking on it.
3551 Choose date in calendar (only if nothing was typed into
3554 ---------- Footnotes ----------
3556 (1) If you don't need/want the calendar, configure the variable
3557 `org-popup-calendar-for-date-prompt'.
3560 File: org, Node: Custom time format, Prev: The date/time prompt, Up: Creating timestamps
3562 8.2.2 Custom time format
3563 ------------------------
3565 Org-mode uses the standard ISO notation for dates and times as it is
3566 defined in ISO 8601. If you cannot get used to this and require another
3567 representation of date and time to keep you happy, you can get it by
3568 customizing the variables `org-display-custom-times' and
3569 `org-time-stamp-custom-formats'.
3572 Toggle the display of custom formats for dates and times.
3574 Org-mode needs the default format for scanning, so the custom date/time
3575 format does not _replace_ the default format - instead it is put _over_
3576 the default format using text properties. This has the following
3578 * You cannot place the cursor onto a time stamp anymore, only before
3581 * The `S-<up>/<down>' keys can no longer be used to adjust each
3582 component of a time stamp. If the cursor is at the beginning of
3583 the stamp, `S-<up>/<down>' will change the stamp by one day, just
3584 like `S-<left>/<right>'. At the end of the stamp, the time will
3585 be changed by one minute.
3587 * If the time stamp contains a range of clock times or a repeater,
3588 these will not be overlayed, but remain in the buffer as they were.
3590 * When you delete a time stamp character-by-character, it will only
3591 disappear from the buffer after _all_ (invisible) characters
3592 belonging to the ISO timestamp have been removed.
3594 * If the custom time stamp format is longer than the default and you
3595 are using dates in tables, table alignment will be messed up. If
3596 the custom format is shorter, things do work as expected.
3599 File: org, Node: Deadlines and scheduling, Next: Clocking work time, Prev: Creating timestamps, Up: Timestamps
3601 8.3 Deadlines and Scheduling
3602 ============================
3604 A time stamp may be preceded by special keywords to facilitate planning
3608 The task (most likely a TODO item) is supposed to be finished on
3609 that date, and it will be listed then. In addition, the
3610 compilation for _today_ will carry a warning about the approaching
3611 or missed deadline, starting `org-deadline-warning-days' before
3612 the due date, and continuing until the entry is marked DONE. An
3615 *** TODO write article about the Earth for the Guide
3616 The editor in charge is [[bbdb:Ford Prefect]]
3617 DEADLINE: <2004-02-29 Sun>
3619 You can specify a different lead time for warnings for a specific
3620 deadlines using the following syntax. Here is an example with a
3621 warning period of 5 days `DEADLINE: <2004-02-29 Sun -5d>'.
3624 You are planning to start working on that task on the given date.
3625 The headline will be listed under the given date(1). In addition,
3626 a reminder that the scheduled date has passed will be present in
3627 the compilation for _today_, until the entry is marked DONE.
3628 I.e., the task will automatically be forwarded until completed.
3630 *** TODO Call Trillian for a date on New Years Eve.
3631 SCHEDULED: <2004-12-25 Sat>
3633 Important: Scheduling an item in Org-mode should not be understood
3634 like Scheduling a meeting. Setting a date for a meeting is just a
3635 simple appointment, you should mark this entry with a simple plain
3636 time stamp, to get this item shown on the date where it applies.
3637 This is a frequent mis-understanding from Org-users. In Org-mode,
3638 Scheduling means setting a date when you want to start working on
3643 * Inserting deadline/schedule:: Planning items
3644 * Repeated tasks:: Items that show up again and again
3646 ---------- Footnotes ----------
3648 (1) It will still be listed on that date after it has been marked
3649 DONE. If you don't like this, set the variable
3650 `org-agenda-skip-scheduled-if-done'.
3653 File: org, Node: Inserting deadline/schedule, Next: Repeated tasks, Prev: Deadlines and scheduling, Up: Deadlines and scheduling
3655 8.3.1 Inserting deadline/schedule
3656 ---------------------------------
3658 The following commands allow to quickly insert a deadline or to schedule
3662 Insert `DEADLINE' keyword along with a stamp. The insertion will
3663 happen in the line directly following the headline.
3666 Create a sparse tree with all deadlines that are either past-due,
3667 or which will become due within `org-deadline-warning-days'. With
3668 `C-u' prefix, show all deadlines in the file. With a numeric
3669 prefix, check that many days. For example, `C-1 C-c C-w' shows
3670 all deadlines due tomorrow.
3673 Insert `SCHEDULED' keyword along with a stamp. The insertion will
3674 happen in the line directly following the headline. Any CLOSED
3675 timestamp will be removed.
3678 File: org, Node: Repeated tasks, Prev: Inserting deadline/schedule, Up: Deadlines and scheduling
3680 8.3.2 Repeated Tasks
3681 --------------------
3683 Some tasks need to be repeated again and again, and Org-mode therefore
3684 allows to use a repeater in a DEADLINE or SCHEDULED time stamp, for
3686 ** TODO Pay the rent
3687 DEADLINE: <2005-10-01 Sat +1m>
3689 Deadlines and scheduled items produce entries in the agenda when they
3690 are over-due, so it is important to be able to mark such an entry as
3691 completed once you have done so. When you mark a DEADLINE or a SCHEDULE
3692 with the todo keyword DONE, it will no longer produce entries in the
3693 agenda. The problem with this is, however, that then also the _next_
3694 instance of the repeated entry will not be active. Org-mode deals with
3695 this in the following way: When you try to mark such an entry DONE
3696 (using `C-c C-t'), it will shift the base date of the repeating time
3697 stamp by the repeater interval, and immediately set the entry state
3698 back to TODO. In the example above, setting the state to DONE would
3699 actually switch the date like this:
3701 ** TODO Pay the rent
3702 DEADLINE: <2005-11-01 Tue +1m>
3704 You will also be prompted for a note that will be put under the
3705 DEADLINE line to keep a record that you actually acted on the previous
3706 instance of this deadline.
3708 As a consequence of shifting the base date, this entry will no
3709 longer be visible in the agenda when checking past dates, but all
3710 future instances will be visible.
3712 You may have both scheduling and deadline information for a specific
3713 task - just make sure that the repeater intervals on both are the same.
3716 File: org, Node: Clocking work time, Prev: Deadlines and scheduling, Up: Timestamps
3718 8.4 Clocking work time
3719 ======================
3721 Org-mode allows you to clock the time you spent on specific tasks in a
3722 project. When you start working on an item, you can start the clock.
3723 When you stop working on that task, or when you mark the task done, the
3724 clock is stopped and the corresponding time interval is recorded. It
3725 also computes the total time spent on each subtree of a project.
3728 Start the clock on the current item (clock-in). This inserts the
3729 CLOCK keyword together with a timestamp.
3732 Stop the clock (clock-out). The inserts another timestamp at the
3733 same location where the clock was last started. It also directly
3734 computes the resulting time in inserts it after the time range as
3735 `=> HH:MM'. See the variable `org-log-done' for the possibility to
3736 record an additional note together with the clock-out time
3740 Recompute the time interval after changing one of the time stamps.
3741 This is only necessary if you edit the time stamps directly. If
3742 you change them with `S-<cursor>' keys, the update is automatic.
3745 Changing the TODO state of an item to DONE automatically stops the
3746 clock if it is running in this same item.
3749 Cancel the current clock. This is useful if a clock was started by
3750 mistake, or if you ended up working on something else.
3753 Display time summaries for each subtree in the current buffer.
3754 This puts overlays at the end of each headline, showing the total
3755 time recorded under that heading, including the time of any
3756 subheadings. You can use visibility cycling to study the tree, but
3757 the overlays disappear when you change the buffer (see variable
3758 `org-remove-highlights-with-change') or press `C-c C-c'.
3761 Insert a dynamic block (*note Dynamic blocks::) containing a clock
3762 report as an org-mode table into the current file.
3763 #+BEGIN: clocktable :maxlevel 2 :emphasize nil
3766 If such a block already exists, its content is replaced by the new
3767 table. The `BEGIN' line can specify options:
3768 :maxlevel Maximum level depth to which times are listed in the table.
3769 :emphasize When `t', emphasize level one and level two items
3770 :scope The scope to consider. This can be any of the following:
3771 nil the current buffer or narrowed region
3772 file the full current buffer
3773 subtree the subtree where the clocktable is located
3774 treeN the surrounding level N tree, for example `tree3'
3775 tree the surrounding level 1 tree
3776 agenda all agenda files
3777 ("file"..) scan these files
3778 :block The time block to consider. This block is specified relative
3779 to the current time and may be any of these keywords:
3780 `today', `yesterday', `thisweek', `lastweek',
3781 `thismonth', `lastmonth', `thisyear', or `lastyear'.
3782 :tstart A time string specifying when to start considering times
3783 :tend A time string specifying when to stop considering times
3784 So to get a clock summary of the current level 1 tree, for the
3785 current day, you could write
3786 #+BEGIN: clocktable :maxlevel 2 :block today :scope tree1
3789 and to use a specific time range you could write(2)
3790 #+BEGIN: clocktable :tstart "<2006-08-10 Thu 10:00>"
3791 :tend "<2006-08-10 Thu 12:00>"
3797 Update dynamical block at point. The cursor needs to be in the
3798 `#+BEGIN' line of the dynamic block.
3801 Update all dynamic blocks (*note Dynamic blocks::). This is
3802 useful if you have several clocktable blocks in a buffer.
3804 The `l' key may be used in the timeline (*note Timeline::) and in
3805 the agenda (*note Weekly/Daily agenda::) to show which tasks have been
3806 worked on or closed during a day.
3808 ---------- Footnotes ----------
3810 (1) The corresponding in-buffer setting is: `#+STARTUP:
3813 (2) Note that all parameters must be specified in a single line -
3814 the line is broken here only to fit it onto the manual.
3817 File: org, Node: Remember, Next: Agenda views, Prev: Timestamps, Up: Top
3822 The Remember package by John Wiegley lets you store quick notes with
3823 little interruption of your work flow. See
3824 `http://www.emacswiki.org/cgi-bin/wiki/RememberMode' for more
3825 information. It is an excellent way to add new notes and TODO items to
3826 Org-mode files. Org-mode significantly expands the possibilities of
3827 remember: You may define templates for different note types, and to
3828 associate target files and headlines with specific templates. It also
3829 allows you to select the location where a note should be stored
3830 interactively, on the fly.
3834 * Setting up remember:: Some code for .emacs to get things going
3835 * Remember templates:: Define the outline of different note types
3836 * Storing notes:: Directly get the note to where it belongs
3839 File: org, Node: Setting up remember, Next: Remember templates, Prev: Remember, Up: Remember
3841 9.1 Setting up remember
3842 =======================
3844 The following customization will tell remember to use org files as
3845 target, and to create annotations compatible with Org-mode links.
3847 (setq org-directory "~/path/to/my/orgfiles/")
3848 (setq org-default-notes-file (concat org-directory "/notes.org"))
3849 (setq remember-annotation-functions '(org-remember-annotation))
3850 (setq remember-handler-functions '(org-remember-handler))
3851 (add-hook 'remember-mode-hook 'org-remember-apply-template)
3854 File: org, Node: Remember templates, Next: Storing notes, Prev: Setting up remember, Up: Remember
3856 9.2 Remember templates
3857 ======================
3859 In combination with Org-mode, you can use templates to generate
3860 different types of remember notes. For example, if you would like to
3861 use one template to create general TODO entries, another one for
3862 journal entries, and a third one for collecting random ideas, you could
3865 (setq org-remember-templates
3866 '((?t "* TODO %?\n %i\n %a" "~/org/TODO.org" "Tasks")
3867 (?j "* %U %?\n\n %i\n %a" "~/org/JOURNAL.org")
3868 (?i "* %^{Title}\n %i\n %a" "~/org/JOURNAL.org" "New Ideas")))
3870 In these entries, the character specifies how to select the template.
3871 The first string specifies the template. Two more (optional) strings
3872 give the file in which, and the headline under which the new note
3873 should be stored. The file defaults (if not present or `nil') to
3874 `org-default-notes-file', the heading to
3875 `org-remember-default-headline'. Both defaults help to get to the
3876 storing location quickly, but you can change the location interactively
3877 while storing the note.
3879 When you call `M-x remember' (or `M-x org-remember') to remember
3880 something, org will prompt for a key to select the template (if you have
3881 more than one template) and then prepare the buffer like
3883 [[file:link to where you called remember]]
3887 * [2006-03-21 Tue 15:37]
3889 [[file:link to where you called remember]]
3891 During expansion of the template, special `%'-escapes allow dynamic
3892 insertion of content:
3893 %^{prompt} prompt the user for a string and replace this sequence with it.
3894 %t time stamp, date only
3895 %T time stamp with date and time
3896 %u, %U like the above, but inactive time stamps
3897 %^t like `%t', but prompt for date. Similarly `%^T', `%^u', `%^U'
3898 You may define a prompt like `%^{Birthday}t'
3899 %n user name (taken from `user-full-name')
3900 %a annotation, normally the link created with `org-store-link'
3901 %A like `%a', but prompt for the description part
3902 %i initial content, the region when remember is called with C-u.
3903 The entire text will be indented like `%i' itself.
3904 %^g prompt for tags, with completion on tags in target file.
3905 %^G prompt for tags, with completion all tags in all agenda files.
3906 %:keyword specific information for certain link types, see below
3908 For specific link types, the following keywords will be defined(1):
3910 Link type | Available keywords
3911 -------------------+----------------------------------------------
3912 bbdb | %:name %:company
3913 vm, wl, mh, rmail | %:type %:subject %:message-id
3914 | %:from %:fromname %:fromaddress
3915 | %:to %:toname %:toaddress
3916 | %:fromto (either "to NAME" or "from NAME")(2)
3917 gnus | %:group, for messages also all email fields
3919 info | %:file %:node
3922 To place the cursor after template expansion use:
3924 %? After completing the template, position cursor here.
3926 If you change you mind about which template to use, call `org-remember'
3927 in the remember buffer. You may then select a new template that will
3928 be filled with the previous context information.
3930 ---------- Footnotes ----------
3932 (1) If you define your own link types (*note Adding hyperlink
3933 types::), any property you store with `org-store-link-props' can be
3934 accessed in remember templates in a similar way.
3936 (2) This will always be the other, not the user. See the variable
3937 `org-from-is-user-regexp'.
3940 File: org, Node: Storing notes, Prev: Remember templates, Up: Remember
3945 When you are finished preparing a note with remember, you have to press
3946 `C-c C-c' to file the note away. The handler will store the note in
3947 the file and under the headline specified in the template, or it will
3948 use the default file and headlines. The window configuration will be
3949 restored, and you are back in the working context before the call to
3950 `remember'. To re-use the location found during the last call to
3951 `remember', exit the remember buffer with `C-u C-u C-c C-c', i.e.
3952 specify a double prefix argument to `C-c C-c'.
3954 If you want to store the note to a different place, use `C-u C-c
3955 C-c' instead to exit remember(1). The handler will then first prompt
3956 for a target file - if you press <RET>, the value specified for the
3957 template is used. Then the command offers the headings tree of the
3958 selected file, with the cursor position at the default headline (if you
3959 had specified one in the template). You can either immediately press
3960 <RET> to get the note placed there. Or you can use the following keys
3961 to find a different location:
3962 <TAB> Cycle visibility.
3963 <down> / <up> Next/previous visible headline.
3964 n / p Next/previous visible headline.
3965 f / b Next/previous headline same level.
3967 Pressing <RET> or <left> or <right> then leads to the following
3970 Cursor Key Note gets inserted
3972 on headline <RET> as sublevel of the heading at cursor, first or
3974 depending on `org-reverse-note-order'.
3975 <left>/<right>as same level, before/after current heading
3976 buffer-start <RET> as level 2 heading at end of file or level 1
3978 depending on `org-reverse-note-order'.
3979 not on <RET> at cursor position, level taken from context.
3982 Before inserting the text into a tree, the function ensures that the
3983 text has a headline, i.e. a first line that starts with a `*'. If not,
3984 a headline is constructed from the current date and some additional
3985 data. If you have indented the text of the note below the headline, the
3986 indentation will be adapted if inserting the note into the tree requires
3987 demotion from level 1.
3989 ---------- Footnotes ----------
3991 (1) Configure the variable `org-remember-store-without-prompt' to
3992 make this behavior the default.
3995 File: org, Node: Agenda views, Next: Embedded LaTeX, Prev: Remember, Up: Top
4000 Due to the way Org-mode works, TODO items, time-stamped items, and
4001 tagged headlines can be scattered throughout a file or even a number of
4002 files. To get an overview over open action items, or over events that
4003 are important for a particular date, this information must be collected,
4004 sorted and displayed in an organized way.
4006 Org-mode can select items based on various criteria, and display them
4007 in a separate buffer. Six different view types are provided:
4009 * an _agenda_ that is like a calendar and shows information for
4012 * a _TODO list_ that covers all unfinished action items,
4014 * a _tags view_, showings headlines based on the tags associated
4017 * a _timeline view_ that shows all events in a single Org-mode file,
4018 in time-sorted view,
4020 * a _stuck projects view_ showing projects that currently don't move
4023 * _custom views_ that are special tag/keyword searches and
4024 combinations of different views.
4026 The extracted information is displayed in a special _agenda buffer_.
4027 This buffer is read-only, but provides commands to visit the
4028 corresponding locations in the original Org-mode files, and even to
4029 edit these files remotely.
4031 Two variables control how the agenda buffer is displayed and whether
4032 the window configuration is restored when the agenda exits:
4033 `org-agenda-window-setup' and `org-agenda-restore-windows-after-quit'.
4037 * Agenda files:: Files being searched for agenda information
4038 * Agenda dispatcher:: Keyboard access to agenda views
4039 * Built-in agenda views:: What is available out of the box?
4040 * Presentation and sorting:: How agenda items are prepared for display
4041 * Agenda commands:: Remote editing of org trees
4042 * Custom agenda views:: Defining special searches and views
4045 File: org, Node: Agenda files, Next: Agenda dispatcher, Prev: Agenda views, Up: Agenda views
4050 The information to be shown is collected from all _agenda files_, the
4051 files listed in the variable `org-agenda-files'(1). Thus even if you
4052 only work with a single Org-mode file, this file should be put into
4053 that list(2). You can customize `org-agenda-files', but the easiest
4054 way to maintain it is through the following commands
4057 Add current file to the list of agenda files. The file is added to
4058 the front of the list. If it was already in the list, it is moved
4059 to the front. With prefix arg, file is added/moved to the end.
4062 Remove current file from the list of agenda files.
4066 Cycle through agenda file list, visiting one file after the other.
4069 Search for a regular rexpression in all agenda files and display
4070 the results in an `occur' buffer.
4072 The Org menu contains the current list of files and can be used to
4075 ---------- Footnotes ----------
4077 (1) If the value of that variable is not a list, but a single file
4078 name, then the list of agenda files will be maintained in that external
4081 (2) When using the dispatcher, pressing `1' before selecting a
4082 command will actually limit the command to the current file, and ignore
4083 `org-agenda-files' until the next dispatcher command.
4086 File: org, Node: Agenda dispatcher, Next: Built-in agenda views, Prev: Agenda files, Up: Agenda views
4088 10.2 The agenda dispatcher
4089 ==========================
4091 The views are created through a dispatcher that should be bound to a
4092 global key, for example `C-c a' (*note Installation::). In the
4093 following we will assume that `C-c a' is indeed how the dispatcher is
4094 accessed and list keyboard access to commands accordingly. After
4095 pressing `C-c a', an additional letter is required to execute a
4096 command. The dispatcher offers the following default commands:
4098 Create the calendar-like agenda (*note Weekly/Daily agenda::).
4101 Create a list of all TODO items (*note Global TODO list::).
4104 Create a list of headlines matching a TAGS expression (*note
4105 Matching tags and properties::).
4108 Create the timeline view for the current buffer (*note Timeline::).
4111 Create a list of stuck projects (*note Stuck projects::).
4114 Restrict an agenda command to the current buffer. After pressing
4115 `1', you still need to press the character selecting the command.
4118 If there is an active region, restrict the following agenda
4119 command to the region. Otherwise, restrict it to the current
4120 subtree. After pressing `0', you still need to press the
4121 character selecting the command.
4123 You can also define custom commands that will be accessible through
4124 the dispatcher, just like the default commands. This includes the
4125 possibility to create extended agenda buffers that contain several
4126 blocks together, for example the weekly agenda, the global TODO list and
4127 a number of special tags matches. *Note Custom agenda views::.
4130 File: org, Node: Built-in agenda views, Next: Presentation and sorting, Prev: Agenda dispatcher, Up: Agenda views
4132 10.3 The built-in agenda views
4133 ==============================
4135 In this section we describe the built-in views.
4139 * Weekly/Daily agenda:: The calendar page with current tasks
4140 * Global TODO list:: All unfinished action items
4141 * Matching tags and properties:: Structured information with fine-tuned search
4142 * Timeline:: Time-sorted view for single file
4143 * Stuck projects:: Find projects you need to review
4146 File: org, Node: Weekly/Daily agenda, Next: Global TODO list, Prev: Built-in agenda views, Up: Built-in agenda views
4148 10.3.1 The weekly/daily agenda
4149 ------------------------------
4151 The purpose of the weekly/daily _agenda_ is to act like a page of a
4152 paper agenda, showing all the tasks for the current week or day.
4155 Compile an agenda for the current week from a list of org files.
4156 The agenda shows the entries for each day. With a `C-u' prefix (or
4157 when the variable `org-agenda-include-all-todo' is `t'), all
4158 unfinished TODO items (including those without a date) are also
4159 listed at the beginning of the buffer, before the first date.
4161 Remote editing from the agenda buffer means, for example, that you
4162 can change the dates of deadlines and appointments from the agenda
4163 buffer. The commands available in the Agenda buffer are listed in
4164 *Note Agenda commands::.
4166 Calendar/Diary integration
4167 ..........................
4169 Emacs contains the calendar and diary by Edward M. Reingold. The
4170 calendar displays a three-month calendar with holidays from different
4171 countries and cultures. The diary allows you to keep track of
4172 anniversaries, lunar phases, sunrise/set, recurrent appointments
4173 (weekly, monthly) and more. In this way, it is quite complementary to
4174 Org-mode. It can be very useful to combine output from Org-mode with
4177 In order to include entries from the Emacs diary into Org-mode's
4178 agenda, you only need to customize the variable
4180 (setq org-agenda-include-diary t)
4182 After that, everything will happen automatically. All diary entries
4183 including holidays, anniversaries etc will be included in the agenda
4184 buffer created by Org-mode. <SPC>, <TAB>, and <RET> can be used from
4185 the agenda buffer to jump to the diary file in order to edit existing
4186 diary entries. The `i' command to insert new entries for the current
4187 date works in the agenda buffer, as well as the commands `S', `M', and
4188 `C' to display Sunrise/Sunset times, show lunar phases and to convert
4189 to other calendars, respectively. `c' can be used to switch back and
4190 forth between calendar and agenda.
4192 If you are using the diary only for sexp entries and holidays, it is
4193 faster to not use the above setting, but instead to copy or even move
4194 the entries into an Org-mode file. Org-mode evaluates diary-style sexp
4195 entries, and does it faster because there is no overhead for first
4196 creating the diary display. Note that the sexp entries must start at
4197 the left margin, no white space is allowed before them. For example,
4198 the following segment of an Org-mode file will be processed and entries
4199 will be made in the agenda:
4201 * Birthdays and similar stuff
4203 %%(org-calendar-holiday) ; special function for holiday names
4205 %%(diary-anniversary 14 5 1956) Arthur Dent is %d years old
4206 %%(diary-anniversary 2 10 1869) Mahatma Gandhi would be %d years old
4209 File: org, Node: Global TODO list, Next: Matching tags and properties, Prev: Weekly/Daily agenda, Up: Built-in agenda views
4211 10.3.2 The global TODO list
4212 ---------------------------
4214 The global TODO list contains all unfinished TODO items, formatted and
4215 collected into a single place.
4218 Show the global TODO list. This collects the TODO items from all
4219 agenda files (*note Agenda views::) into a single buffer. The
4220 buffer is in `agenda-mode', so there are commands to examine and
4221 manipulate the TODO entries directly from that buffer (*note
4225 Like the above, but allows selection of a specific TODO keyword.
4226 You can also do this by specifying a prefix argument to `C-c a t'.
4227 With a `C-u' prefix you are prompted for a keyword, and you may
4228 also specify several keywords by separating them with `|' as
4229 boolean OR operator. With a numeric prefix, the Nth keyword in
4230 `org-todo-keywords' is selected. The `r' key in the agenda buffer
4231 regenerates it, and you can give a prefix argument to this command
4232 to change the selected TODO keyword, for example `3 r'. If you
4233 often need a search for a specific keyword, define a custom
4234 command for it (*note Agenda dispatcher::).
4235 Matching specific TODO keywords can also be done as part of a tags
4236 search (*note Tag searches::).
4238 Remote editing of TODO items means that you can change the state of a
4239 TODO entry with a single key press. The commands available in the TODO
4240 list are described in *Note Agenda commands::.
4242 Normally the global todo list simply shows all headlines with TODO
4243 keywords. This list can become very long. There are two ways to keep
4245 - Some people view a TODO item that has been _scheduled_ for
4246 execution (*note Time stamps::) as no longer _open_. Configure the
4247 variable `org-agenda-todo-ignore-scheduled' to exclude scheduled
4248 items from the global TODO list.
4250 - TODO items may have sublevels to break up the task into subtasks.
4251 In such cases it may be enough to list only the highest level TODO
4252 headline and omit the sublevels from the global list. Configure
4253 the variable `org-agenda-todo-list-sublevels' to get this behavior.
4256 File: org, Node: Matching tags and properties, Next: Timeline, Prev: Global TODO list, Up: Built-in agenda views
4258 10.3.3 Matching Tags and Properties
4259 -----------------------------------
4261 If headlines in the agenda files are marked with _tags_ (*note Tags::),
4262 you can select headlines based on the tags that apply to them and
4263 collect them into an agenda buffer.
4266 Produce a list of all headlines that match a given set of tags.
4267 The command prompts for a selection criterion, which is a boolean
4268 logic expression with tags, like `+WORK+URGENT-WITHBOSS' or
4269 `WORK|HOME' (*note Tags::). If you often need a specific search,
4270 define a custom command for it (*note Agenda dispatcher::).
4273 Like `C-c a m', but only select headlines that are also TODO items
4274 and force checking subitems (see variable
4275 `org-tags-match-list-sublevels'). Matching specific todo keywords
4276 together with a tags match is also possible, see *Note Tag
4279 The commands available in the tags list are described in *Note
4283 File: org, Node: Timeline, Next: Stuck projects, Prev: Matching tags and properties, Up: Built-in agenda views
4285 10.3.4 Timeline for a single file
4286 ---------------------------------
4288 The timeline summarizes all time-stamped items from a single Org-mode
4289 file in a _time-sorted view_. The main purpose of this command is to
4290 give an overview over events in a project.
4293 Show a time-sorted view of the org file, with all time-stamped
4294 items. When called with a `C-u' prefix, all unfinished TODO
4295 entries (scheduled or not) are also listed under the current date.
4297 The commands available in the timeline buffer are listed in *Note
4301 File: org, Node: Stuck projects, Prev: Timeline, Up: Built-in agenda views
4303 10.3.5 Stuck projects
4304 ---------------------
4306 If you are following a system like David Allen's GTD to organize your
4307 work, one of the "duties" you have is a regular review to make sure
4308 that all projects move along. A _stuck_ project is a project that has
4309 no defined next actions, so it will never show up in the TODO lists
4310 Org-mode produces. During the review, you need to identify such
4311 projects and define next actions for them.
4314 List projects that are stuck.
4317 Customize the variable `org-stuck-projects' to define what a stuck
4318 project is and how to find it.
4320 You almost certainly will have to configure this view before it will
4321 work for you. The built-in default assumes that all your projects are
4322 level-2 headlines, and that a project is not stuck if it has at least
4323 one entry marked with a todo keyword TODO or NEXT or NEXTACTION.
4325 Lets assume that you, in your own way of using Org-mode, identify
4326 projects with a tag PROJECT, and that you use a todo keyword MAYBE to
4327 indicate a project that should not be considered yet. Lets further
4328 assume that the todo keyword DONE marks finished projects, and that NEXT
4329 and TODO indicate next actions. The tag @SHOP indicates shopping and
4330 is a next action even without the NEXT tag. Finally, if the project
4331 contains the special word IGNORE anywhere, it should not be listed
4332 either. In this case you would start by identifying eligible projects
4333 with a tags/todo match `+PROJECT/-MAYBE-DONE', and then check for TODO,
4334 NEXT, @SHOP, and IGNORE in the subtree to identify projects that are
4335 not stuck. The correct customization for this is
4337 (setq org-stuck-projects
4338 '("+PROJECT/-MAYBE-DONE" ("NEXT" "TODO") ("@SHOP")
4342 File: org, Node: Presentation and sorting, Next: Agenda commands, Prev: Built-in agenda views, Up: Agenda views
4344 10.4 Presentation and sorting
4345 =============================
4347 Before displaying items in an agenda view, Org-mode visually prepares
4348 the items and sorts them. Each item occupies a single line. The line
4349 starts with a _prefix_ that contains the _category_ (*note
4350 Categories::) of the item and other important information. You can
4351 customize the prefix using the option `org-agenda-prefix-format'. The
4352 prefix is followed by a cleaned-up version of the outline headline
4353 associated with the item.
4357 * Categories:: Not all tasks are equal
4358 * Time-of-day specifications:: How the agenda knows the time
4359 * Sorting of agenda items:: The order of things
4362 File: org, Node: Categories, Next: Time-of-day specifications, Prev: Presentation and sorting, Up: Presentation and sorting
4367 The category is a broad label assigned to each agenda item. By default,
4368 the category is simply derived from the file name, but you can also
4369 specify it with a special line in the buffer, like this(1):
4373 If you would like to have a special CATEGORY for a single entry or a
4374 (sub)tree, give the entry a `:CATEGORY:' property with the location as
4375 the value (*note Properties and columns::).
4377 The display in the agenda buffer looks best if the category is not
4378 longer than 10 characters.
4380 ---------- Footnotes ----------
4382 (1) If there are several such lines in a file, each specifies the
4383 category for the text below it. The first category also applies to any
4384 text before the first CATEGORY line. This method is only kept for
4385 backward compatibility. The preferred method for setting multiple
4386 categories in a buffer is using a property.
4389 File: org, Node: Time-of-day specifications, Next: Sorting of agenda items, Prev: Categories, Up: Presentation and sorting
4391 10.4.2 Time-of-Day Specifications
4392 ---------------------------------
4394 Org-mode checks each agenda item for a time-of-day specification. The
4395 time can be part of the time stamp that triggered inclusion into the
4396 agenda, for example as in `<2005-05-10 Tue 19:00>'. Time ranges can be
4397 specified with two time stamps, like
4398 `<2005-05-10 Tue 20:30>--<2005-05-10 Tue 22:15>'.
4400 In the headline of the entry itself, a time(range) may also appear as
4401 plain text (like `12:45' or a `8:30-1pm'. If the agenda integrates the
4402 Emacs diary (*note Weekly/Daily agenda::), time specifications in diary
4403 entries are recognized as well.
4405 For agenda display, Org-mode extracts the time and displays it in a
4406 standard 24 hour format as part of the prefix. The example times in
4407 the previous paragraphs would end up in the agenda like this:
4409 8:30-13:00 Arthur Dent lies in front of the bulldozer
4410 12:45...... Ford Prefect arrives and takes Arthur to the pub
4411 19:00...... The Vogon reads his poem
4412 20:30-22:15 Marwin escorts the Hitchhikers to the bridge
4414 If the agenda is in single-day mode, or for the display of today, the
4415 timed entries are embedded in a time grid, like
4417 8:00...... ------------------
4418 8:30-13:00 Arthur Dent lies in front of the bulldozer
4419 10:00...... ------------------
4420 12:00...... ------------------
4421 12:45...... Ford Prefect arrives and takes Arthur to the pub
4422 14:00...... ------------------
4423 16:00...... ------------------
4424 18:00...... ------------------
4425 19:00...... The Vogon reads his poem
4426 20:00...... ------------------
4427 20:30-22:15 Marwin escorts the Hitchhikers to the bridge
4429 The time grid can be turned on and off with the variable
4430 `org-agenda-use-time-grid', and can be configured with
4431 `org-agenda-time-grid'.
4434 File: org, Node: Sorting of agenda items, Prev: Time-of-day specifications, Up: Presentation and sorting
4436 10.4.3 Sorting of agenda items
4437 ------------------------------
4439 Before being inserted into a view, the items are sorted. How this is
4440 done depends on the type of view.
4441 * For the daily/weekly agenda, the items for each day are sorted.
4442 The default order is to first collect all items containing an
4443 explicit time-of-day specification. These entries will be shown
4444 at the beginning of the list, as a _schedule_ for the day. After
4445 that, items remain grouped in categories, in the sequence given by
4446 `org-agenda-files'. Within each category, items are sorted by
4447 priority (*note Priorities::), which is composed of the base
4448 priority (2000 for priority `A', 1000 for `B', and 0 for `C'),
4449 plus additional increments for overdue scheduled or deadline items.
4451 * For the TODO list, items remain in the order of categories, but
4452 within each category, sorting takes place according to priority
4453 (*note Priorities::).
4455 * For tags matches, items are not sorted at all, but just appear in
4456 the sequence in which they are found in the agenda files.
4458 Sorting can be customized using the variable
4459 `org-agenda-sorting-strategy'.
4462 File: org, Node: Agenda commands, Next: Custom agenda views, Prev: Presentation and sorting, Up: Agenda views
4464 10.5 Commands in the agenda buffer
4465 ==================================
4467 Entries in the agenda buffer are linked back to the org file or diary
4468 file where they originate. You are not allowed to edit the agenda
4469 buffer itself, but commands are provided to show and jump to the
4470 original entry location, and to edit the org-files "remotely" from the
4471 agenda buffer. In this way, all information is stored only once,
4472 removing the risk that your agenda and note files may diverge.
4474 Some commands can be executed with mouse clicks on agenda lines. For
4475 the other commands, the cursor needs to be in the desired line.
4481 Next line (same as <up>).
4484 Previous line (same as <down>).
4491 Display the original location of the item in another window.
4494 Display original location and recenter that window.
4499 Go to the original location of the item in another window. Under
4500 Emacs 22, `mouse-1' will also works for this.
4503 Go to the original location of the item and delete other windows.
4506 Toggle Follow mode. In Follow mode, as you move the cursor through
4507 the agenda buffer, the other window always shows the corresponding
4508 location in the org file. The initial setting for this mode in new
4509 agenda buffers can be set with the variable
4510 `org-agenda-start-with-follow-mode'.
4513 Display the entire subtree of the current item in an indirect
4514 buffer. With numerical prefix ARG, go up to this level and then
4515 take that tree. If ARG is negative, go up that many levels. With
4516 `C-u' prefix, do not remove the previously used indirect buffer.
4519 Toggle Logbook mode. In Logbook mode, entries that where marked
4520 DONE while logging was on (variable `org-log-done') are shown in
4521 the agenda, as are entries that have been clocked on that day.
4527 Delete other windows.
4530 Switch to day/week/month/year view. When switching to day or week
4531 view, this setting becomes the default for subseqent agenda
4532 commands. Since month and year views are slow to create, the do
4533 not become the default.
4536 Toggle the inclusion of diary entries. See *Note Weekly/Daily
4540 Toggle the time grid on and off. See also the variables
4541 `org-agenda-use-time-grid' and `org-agenda-time-grid'.
4544 Recreate the agenda buffer, for example to reflect the changes
4545 after modification of the time stamps of items with S-<left> and
4546 S-<right>. When the buffer is the global todo list, a prefix
4547 argument is interpreted to create a selective list for a specific
4551 Save all Org-mode buffers in the current Emacs session.
4554 Display the following `org-agenda-ndays' days. For example, if
4555 the display covers a week, switch to the following week. With
4556 prefix arg, go forward that many times `org-agenda-ndays' days.
4559 Display the previous dates.
4571 Undo a change due to a remote editing command. The change is
4572 undone both in the agenda buffer and in the remote buffer.
4575 Change the TODO state of the item, both in the agenda and in the
4579 Delete the current agenda item along with the entire subtree
4580 belonging to it in the original Org-mode file. If the text to be
4581 deleted remotely is longer than one line, the kill needs to be
4582 confirmed by the user. See variable `org-agenda-confirm-kill'.
4585 Archive the subtree corresponding to the current headline.
4588 Show all tags associated with the current item. Because of
4589 inheritance, this may be more than the tags listed in the line
4593 Set tags for the current headline. If there is an active region
4594 in the agenda, change a tag for all headings in the region.
4597 Toggle the ARCHIVE tag for the current headline.
4600 Set the priority for the current item. Org-mode prompts for the
4601 priority character. If you reply with <SPC>, the priority cookie
4602 is removed from the entry.
4605 Display weighted priority of current item.
4609 Increase the priority of the current item. The priority is
4610 changed in the original buffer, but the agenda is not resorted.
4611 Use the `r' key for this.
4615 Decrease the priority of the current item.
4621 Set a deadline for this item.
4624 Change the time stamp associated with the current line by one day
4625 into the future. With prefix argument, change it by that many
4626 days. For example, `3 6 5 S-<right>' will change it by a year.
4627 The stamp is changed in the original org file, but the change is
4628 not directly reflected in the agenda buffer. Use the `r' key to
4632 Change the time stamp associated with the current line by one day
4636 Change the time stamp associated with the current line to today.
4637 The key `>' has been chosen, because it is the same as `S-.' on my
4641 Start the clock on the current item. If a clock is running
4642 already, it is stopped first.
4645 Stop the previously started clock.
4648 Cancel the currently running clock.
4654 Open the Emacs calendar and move to the date at the agenda cursor.
4657 When in the calendar, compute and show the Org-mode agenda for the
4661 Insert a new entry into the diary. Prompts for the type of entry
4662 (day, weekly, monthly, yearly, anniversary, cyclic) and creates a
4663 new entry in the diary, just as `i d' etc. would do in the
4664 calendar. The date is taken from the cursor position.
4667 Show the phases of the moon for the three months around current
4671 Show sunrise and sunset times. The geographical location must be
4672 set with calendar variables, see documentation of the Emacs
4676 Convert the date at cursor into many other cultural and historic
4680 Show holidays for three month around the cursor date.
4683 Export a single iCalendar file containing entries from all agenda
4690 Write the agenda view to a file. Depending on the extension of the
4691 selected file name, the view will be exported as HTML (extension
4692 `.html' or `.htm'), Postscript (extension `.ps'), or plain text
4693 (any other extension). Use the variable
4694 `org-agenda-exporter-settings' to set options for `ps-print' and
4695 for `htmlize' to be used during export.
4701 Quit agenda, remove the agenda buffer.
4704 Exit agenda, remove the agenda buffer and all buffers loaded by
4705 Emacs for the compilation of the agenda. Buffers created by the
4706 user to visit org files will not be removed.
4709 File: org, Node: Custom agenda views, Prev: Agenda commands, Up: Agenda views
4711 10.6 Custom agenda views
4712 ========================
4714 Custom agenda commands serve two purposes: to store and quickly access
4715 frequently used TODO and tags searches, and to create special composite
4716 agenda buffers. Custom agenda commands will be accessible through the
4717 dispatcher (*note Agenda dispatcher::), just like the default commands.
4721 * Storing searches:: Type once, use often
4722 * Block agenda:: All the stuff you need in a single buffer
4723 * Setting Options:: Changing the rules
4724 * Exporting Agenda Views:: Writing agendas to files.
4725 * Extracting Agenda Information for other programs::
4728 File: org, Node: Storing searches, Next: Block agenda, Prev: Custom agenda views, Up: Custom agenda views
4730 10.6.1 Storing searches
4731 -----------------------
4733 The first application of custom searches is the definition of keyboard
4734 shortcuts for frequently used searches, either creating an agenda
4735 buffer, or a sparse tree (the latter covering of course only the current
4736 buffer). Custom commands are configured in the variable
4737 `org-agenda-custom-commands'. You can customize this variable, for
4738 example by pressing `C-c a C'. You can also directly set it with Emacs
4739 Lisp in `.emacs'. The following example contains all valid search
4742 (setq org-agenda-custom-commands
4743 '(("w" todo "WAITING")
4744 ("W" todo-tree "WAITING")
4745 ("u" tags "+BOSS-URGENT")
4746 ("v" tags-todo "+BOSS-URGENT")
4747 ("U" tags-tree "+BOSS-URGENT")
4748 ("f" occur-tree "\\<FIXME\\>")))
4750 The initial single-character string in each entry defines the character
4751 you have to press after the dispatcher command `C-c a' in order to
4752 access the command. The second parameter is the search type, followed
4753 by the string or regular expression to be used for the matching. The
4754 example above will therefore define:
4757 as a global search for TODO entries with `WAITING' as the TODO
4761 as the same search, but only in the current buffer and displaying
4762 the results as a sparse tree
4765 as a global tags search for headlines marked `:BOSS:' but not
4769 as the same search as `C-c a u', but limiting the search to
4770 headlines that are also TODO items
4773 as the same search as `C-c a u', but only in the current buffer and
4774 displaying the result as a sparse tree
4777 to create a sparse tree (again: current buffer only) with all
4778 entries containing the word `FIXME'.
4781 File: org, Node: Block agenda, Next: Setting Options, Prev: Storing searches, Up: Custom agenda views
4786 Another possibility is the construction of agenda views that comprise
4787 the results of _several_ commands, each of which creates a block in the
4788 agenda buffer. The available commands include `agenda' for the daily
4789 or weekly agenda (as created with `C-c a a'), `alltodo' for the global
4790 todo list (as constructed with `C-c a t'), and the matching commands
4791 discussed above: `todo', `tags', and `tags-todo'. Here are two
4794 (setq org-agenda-custom-commands
4795 '(("h" "Agenda and Home-related tasks"
4799 ("o" "Agenda and Office-related tasks"
4804 This will define `C-c a h' to create a multi-block view for stuff you
4805 need to attend to at home. The resulting agenda buffer will contain
4806 your agenda for the current week, all TODO items that carry the tag
4807 `HOME', and also all lines tagged with `GARDEN'. Finally the command
4808 `C-c a o' provides a similar view for office tasks.
4811 File: org, Node: Setting Options, Next: Exporting Agenda Views, Prev: Block agenda, Up: Custom agenda views
4813 10.6.3 Setting Options for custom commands
4814 ------------------------------------------
4816 Org-mode contains a number of variables regulating agenda construction
4817 and display. The global variables define the behavior for all agenda
4818 commands, including the custom commands. However, if you want to change
4819 some settings just for a single custom view, you can do so. Setting
4820 options requires inserting a list of variable names and values at the
4821 right spot in `org-agenda-custom-commands'. For example:
4823 (setq org-agenda-custom-commands
4824 '(("w" todo "WAITING"
4825 ((org-agenda-sorting-strategy '(priority-down))
4826 (org-agenda-prefix-format " Mixed: ")))
4827 ("U" tags-tree "+BOSS-URGENT"
4828 ((org-show-following-heading nil)
4829 (org-show-hierarchy-above nil)))))
4831 Now the `C-c a w' command will sort the collected entries only by
4832 priority, and the prefix format is modified to just say ` Mixed:'
4833 instead of giving the category of the entry. The sparse tags tree of
4834 `C-c a U' will now turn out ultra-compact, because neither the headline
4835 hierarchy above the match, nor the headline following the match will be
4838 For command sets creating a block agenda,
4839 `org-agenda-custom-commands' has two separate spots for setting
4840 options. You can add options that should be valid for just a single
4841 command in the set, and options that should be valid for all commands in
4842 the set. The former are just added to the command entry, the latter
4843 must come after the list of command entries. Going back to the block
4844 agenda example (*note Block agenda::), let's change the sorting strategy
4845 for the `C-c a h' commands to `priority-down', but let's sort the
4846 results for GARDEN tags query in the opposite order, `priority-up'.
4847 This would look like this:
4849 (setq org-agenda-custom-commands
4850 '(("h" "Agenda and Home-related tasks"
4854 ((org-agenda-sorting-strategy '(priority-up)))))
4855 ((org-agenda-sorting-strategy '(priority-down))))
4856 ("o" "Agenda and Office-related tasks"
4861 As you see, the values and parenthesis setting is a little complex.
4862 When in doubt, use the customize interface to set this variable - it
4863 fully supports its structure. Just one caveat: When setting options in
4864 this interface, the _values_ are just lisp expressions. So if the
4865 value is a string, you need to add the double quotes around the value
4869 File: org, Node: Exporting Agenda Views, Next: Extracting Agenda Information for other programs, Prev: Setting Options, Up: Custom agenda views
4871 10.6.4 Exporting Agenda Views
4872 -----------------------------
4874 If you are away from your computer, it can be very useful to have a
4875 printed version of some agenda views to carry around. Org-mode can
4876 export custom agenda views as plain text, HTML(1) and postscript. If
4877 you want to do this only occasionally, use the command
4880 Write the agenda view to a file. Depending on the extension of the
4881 selected file name, the view will be exported as HTML (extension
4882 `.html' or `.htm'), Postscript (extension `.ps'), or plain text
4883 (any other extension). Use the variable
4884 `org-agenda-exporter-settings' to set options for `ps-print' and
4885 for `htmlize' to be used during export, for example
4886 (setq org-agenda-exporter-settings
4887 '((ps-number-of-columns 2)
4888 (ps-landscape-mode t)
4889 (htmlize-output-type 'css)))
4891 If you need to export certain agenda views frequently, you can
4892 associate any custom agenda command with a list of output file names
4893 (2). Here is an example that first does define custom commands for the
4894 agenda and the global todo list, together with a number of files to
4895 which to export them. Then we define two block agenda commands and
4896 specify filenames for them as well. File names can be relative to the
4897 current working directory, or absolute.
4899 (setq org-agenda-custom-commands
4900 '(("X" agenda "" nil ("agenda.html" "agenda.ps"))
4901 ("Y" alltodo "" nil ("todo.html" "todo.txt" "todo.ps"))
4902 ("h" "Agenda and Home-related tasks"
4907 ("~/views/home.html"))
4908 ("o" "Agenda and Office-related tasks"
4913 ("~/views/office.ps"))))
4915 The extension of the file name determines the type of export. If it
4916 is `.html', Org-mode will use the `htmlize.el' package to convert the
4917 buffer to HTML and save it to this file name. If the extension is
4918 `.ps', `ps-print-buffer-with-faces' is used to produce postscript
4919 output. Any other extension produces a plain ASCII file.
4921 The export files are _not_ created when you use one of those
4922 commands interactively. Instead, there is a special command to produce
4923 _all_ specified files in one step:
4926 Export all agenda views that have export filenames associated with
4929 You can use the options section of the custom agenda commands to also
4930 set options for the export commands. For example:
4932 (setq org-agenda-custom-commands
4934 ((ps-number-of-columns 2)
4935 (ps-landscape-mode t)
4936 (org-agenda-prefix-format " [ ] ")
4937 (org-agenda-with-colors nil)
4938 (org-agenda-remove-tags t))
4941 This command sets two options for the postscript exporter, to make it
4942 print in two columns in landscape format - the resulting page can be cut
4943 in two and then used in a paper agenda. The remaining settings modify
4944 the agenda prefix to omit category and scheduling information, and
4945 instead include a checkbox to check off items. We also remove the tags
4946 to make the lines compact, and we don't want to use colors for the
4947 black-and-white printer. Settings specified in
4948 `org-agenda-exporter-settings' will also apply, but the settings in
4949 `org-agenda-custom-commands' take precedence.
4951 From the command line you may also use
4952 emacs -f org-batch-store-agenda-views -kill
4953 or, if you need to modify some parameters
4954 emacs -eval '(org-batch-store-agenda-views \
4955 org-agenda-ndays 30 \
4956 org-agenda-include-diary nil \
4957 org-agenda-files (quote ("~/org/project.org")))' \
4959 which will create the agenda views restricted to the file
4960 `~/org/project.org', without diary entries and with 30 days extent.
4962 ---------- Footnotes ----------
4964 (1) You need to install Hrvoje Niksic' `htmlize.el'.
4966 (2) If you want to store standard views like the weekly agenda or
4967 the global TODO list as well, you need to define custom commands for
4968 them in order to be able to specify filenames.
4971 File: org, Node: Extracting Agenda Information for other programs, Prev: Exporting Agenda Views, Up: Custom agenda views
4973 10.6.5 Extracting Agenda Information for other programs
4974 -------------------------------------------------------
4976 Org-mode provides commands to access agenda information for the command
4977 line in emacs batch mode. This extracted information can be sent
4978 directly to a printer, or it can be read by a program that does further
4979 processing of the data. The first of these commands is the function
4980 `org-batch-agenda', that produces an agenda view and sends it as ASCII
4981 text to STDOUT. The command takes a single string as parameter. If
4982 the string has length 1, it is used as a key to one of the commands you
4983 have configured in `org-agenda-custom-commands', basically any key you
4984 can use after `C-c a'. For example, to directly print the current TODO
4987 emacs -batch -l ~/.emacs -eval '(org-batch-agenda "t")' | lpr
4989 If the parameter is a string with 2 or more characters, it is used
4990 as a tags/todo match string. For example, to print your local shopping
4991 list (all items with the tag `shop', but excluding the tag `NewYork'),
4994 emacs -batch -l ~/.emacs \
4995 -eval '(org-batch-agenda "+shop-NewYork")' | lpr
4997 You may also modify parameters on the fly like this:
4999 emacs -batch -l ~/.emacs \
5000 -eval '(org-batch-agenda "a" \
5001 org-agenda-ndays 30 \
5002 org-agenda-include-diary nil \
5003 org-agenda-files (quote ("~/org/project.org")))' \
5006 which will produce a 30 day agenda, fully restricted to the Org file
5007 `~/org/projects.org', not even including the diary.
5009 If you want to process the agenda data in more sophisticated ways,
5010 you can use the command `org-batch-agenda-csv' to get a comma-separated
5011 list of values for each agenda item. Each line in the output will
5012 contain a number of fields separated by commas. The fields in a line
5015 category The category of the item
5016 head The headline, without TODO kwd, TAGS and PRIORITY
5017 type The type of the agenda entry, can be
5018 todo selected in TODO match
5019 tagsmatch selected in tags match
5020 diary imported from diary
5023 timestamp appointment, selected by timestamp
5024 closed entry was closed on date
5025 upcoming-deadline warning about nearing deadline
5026 past-scheduled forwarded scheduled item
5027 block entry has date block including date
5028 todo The todo keyword, if any
5029 tags All tags including inherited ones, separated by colons
5030 date The relevant date, like 2007-2-14
5031 time The time, like 15:00-16:50
5032 extra String with extra planning info
5033 priority-l The priority letter if any was given
5034 priority-n The computed numerical priority
5036 Time and date will only be given if a timestamp (or deadline/scheduled)
5037 lead to the selection of the item.
5039 A CSV list like this is very easy to use in a post processing script.
5040 For example, here is a Perl program that gets the TODO list from
5041 Emacs/org-mode and prints all the items, preceded by a checkbox:
5045 # define the Emacs command to run
5046 $cmd = "emacs -batch -l ~/.emacs -eval '(org-batch-agenda-csv \"t\")'";
5048 # run it and capture the output
5049 $agenda = qx{$cmd 2>/dev/null};
5051 # loop over all lines
5052 foreach $line (split(/\n/,$agenda)) {
5054 # get the individual values
5055 ($category,$head,$type,$todo,$tags,$date,$time,$extra,
5056 $priority_l,$priority_n) = split(/,/,$line);
5058 # proccess and print
5059 print "[ ] $head\n";
5063 File: org, Node: Embedded LaTeX, Next: Exporting, Prev: Agenda views, Up: Top
5068 Plain ASCII is normally sufficient for almost all note taking. One
5069 exception, however, are scientific notes which need to be able to
5070 contain mathematical symbols and the occasional formula. LaTeX(1) is
5071 widely used to typeset scientific documents. Org-mode supports
5072 embedding LaTeX code into its files, because many academics are used to
5073 read LaTeX source code, and because it can be readily processed into
5074 images for HTML production.
5076 It is not necessary to mark LaTeX macros and code in any special way.
5077 If you observe a few conventions, Org-mode knows how to find it and what
5082 * Math symbols:: TeX macros for symbols and Greek letters
5083 * Subscripts and Superscripts:: Simple syntax for raising/lowering text
5084 * LaTeX fragments:: Complex formulas made easy
5085 * Processing LaTeX fragments:: Previewing LaTeX processing
5086 * CDLaTeX mode:: Speed up entering of formulas
5088 ---------- Footnotes ----------
5090 (1) LaTeX is a macro system based on Donald E. Knuth's TeX system.
5091 Many of the features described here as "LaTeX" are really from TeX, but
5092 for simplicity I am blurring this distinction.
5095 File: org, Node: Math symbols, Next: Subscripts and Superscripts, Prev: Embedded LaTeX, Up: Embedded LaTeX
5100 You can use LaTeX macros to insert special symbols like `\alpha' to
5101 indicate the Greek letter, or `\to' to indicate an arrow. Completion
5102 for these macros is available, just type `\' and maybe a few letters,
5103 and press `M-<TAB>' to see possible completions. Unlike LaTeX code,
5104 Org-mode allows these macros to be present without surrounding math
5105 delimiters, for example:
5107 Angles are written as Greek letters \alpha, \beta and \gamma.
5109 During HTML export (*note HTML export::), these symbols are
5110 translated into the proper syntax for HTML, for the above examples this
5111 is `α' and `→', respectively.
5114 File: org, Node: Subscripts and Superscripts, Next: LaTeX fragments, Prev: Math symbols, Up: Embedded LaTeX
5116 11.2 Subscripts and Superscripts
5117 ================================
5119 Just like in LaTeX, `^' and `_' are used to indicate super- and
5120 subscripts. Again, these can be used without embedding them in
5121 math-mode delimiters. To increase the readability of ASCII text, it is
5122 not necessary (but OK) to surround multi-character sub- and superscripts
5123 with curly braces. For example
5125 The mass if the sun is M_sun = 1.989 x 10^30 kg. The radius of
5126 the sun is R_{sun} = 6.96 x 10^8 m.
5128 To avoid interpretation as raised or lowered text, you can quote `^'
5129 and `_' with a backslash: `\_' and `\^'.
5131 During HTML export (*note HTML export::), subscript and superscripts
5132 are surrounded with `<sub>' and `<sup>' tags, respectively.
5135 File: org, Node: LaTeX fragments, Next: Processing LaTeX fragments, Prev: Subscripts and Superscripts, Up: Embedded LaTeX
5137 11.3 LaTeX fragments
5138 ====================
5140 With symbols, sub- and superscripts, HTML is pretty much at its end when
5141 it comes to representing mathematical formulas(1). More complex
5142 expressions need a dedicated formula processor. To this end, Org-mode
5143 can contain arbitrary LaTeX fragments. It provides commands to preview
5144 the typeset result of these fragments, and upon export to HTML, all
5145 fragments will be converted to images and inlined into the HTML
5146 document(2). For this to work you need to be on a system with a working
5147 LaTeX installation. You also need the `dvipng' program, available at
5148 `http://sourceforge.net/projects/dvipng/'. The LaTeX header that will
5149 be used when processing a fragment can be configured with the variable
5150 `org-format-latex-header'.
5152 LaTeX fragments don't need any special marking at all. The following
5153 snippets will be identified as LaTeX source code:
5154 * Environments of any kind. The only requirement is that the
5155 `\begin' statement appears on a new line, preceded by only
5158 * Text within the usual LaTeX math delimiters. To avoid conflicts
5159 with currency specifications, single `$' characters are only
5160 recognized as math delimiters if the enclosed text contains at
5161 most two line breaks, is directly attached to the `$' characters
5162 with no whitespace in between, and if the closing `$' is followed
5163 by whitespace or punctuation. For the other delimiters, there is
5164 no such restriction, so when in doubt, use `\(...\)' as inline
5169 \begin{equation} % arbitrary environments,
5170 x=\sqrt{b} % even tables, figures
5171 \end{equation} % etc
5173 If $a^2=b$ and \( b=2 \), then the solution must be
5174 either $$ a=+\sqrt{2} $$ or \[ a=-\sqrt{2} \].
5176 If you need any of the delimiter ASCII sequences for other purposes, you
5177 can configure the option `org-format-latex-options' to deselect the
5178 ones you do not wish to have interpreted by the LaTeX converter.
5180 ---------- Footnotes ----------
5182 (1) Yes, there is MathML, but that is not yet fully supported by
5183 many browsers, and there is no decent converter for turning LaTeX or
5184 ASCII representations of formulas into MathML. So for the time being,
5185 converting formulas into images seems the way to go.
5187 (2) The LaTeX export will not use images for displaying LaTeX
5188 fragments but include these fragments directly into the LaTeX code.
5191 File: org, Node: Processing LaTeX fragments, Next: CDLaTeX mode, Prev: LaTeX fragments, Up: Embedded LaTeX
5193 11.4 Processing LaTeX fragments
5194 ===============================
5196 LaTeX fragments can be processed to produce a preview images of the
5197 typeset expressions:
5200 Produce a preview image of the LaTeX fragment at point and overlay
5201 it over the source code. If there is no fragment at point,
5202 process all fragments in the current entry (between two
5203 headlines). When called with a prefix argument, process the
5204 entire subtree. When called with two prefix arguments, or when
5205 the cursor is before the first headline, process the entire buffer.
5208 Remove the overlay preview images.
5210 During HTML export (*note HTML export::), all LaTeX fragments are
5211 converted into images and inlined into the document if the following
5214 (setq org-export-with-LaTeX-fragments t)
5217 File: org, Node: CDLaTeX mode, Prev: Processing LaTeX fragments, Up: Embedded LaTeX
5219 11.5 Using CDLaTeX to enter math
5220 ================================
5222 CDLaTeX-mode is a minor mode that is normally used in combination with a
5223 major LaTeX mode like AUCTeX in order to speed-up insertion of
5224 environments and math templates. Inside Org-mode, you can make use of
5225 some of the features of cdlatex-mode. You need to install `cdlatex.el'
5226 and `texmathp.el' (the latter comes also with AUCTeX) from
5227 `http://www.astro.uva.nl/~dominik/Tools/cdlatex'. Don't turn
5228 cdlatex-mode itself under Org-mode, but use the light version
5229 `org-cdlatex-mode' that comes as part of Org-mode. Turn it on for the
5230 current buffer with `M-x org-cdlatex-mode', or for all Org-mode files
5233 (add-hook 'org-mode-hook 'turn-on-org-cdlatex)
5235 When this mode is enabled, the following features are present (for
5236 more details see the documentation of cdlatex-mode):
5237 * Environment templates can be inserted with `C-c {'.
5239 * The <TAB> key will do template expansion if the cursor is inside a
5240 LaTeX fragment(1). For example, <TAB> will expand `fr' to
5241 `\frac{}{}' and position the cursor correctly inside the first
5242 brace. Another <TAB> will get you into the second brace. Even
5243 outside fragments, <TAB> will expand environment abbreviations at
5244 the beginning of a line. For example, if you write `equ' at the
5245 beginning of a line and press <TAB>, this abbreviation will be
5246 expanded to an `equation' environment. To get a list of all
5247 abbreviations, type `M-x cdlatex-command-help'.
5249 * Pressing `_' and `^' inside a LaTeX fragment will insert these
5250 characters together with a pair of braces. If you use <TAB> to
5251 move out of the braces, and if the braces surround only a single
5252 character or macro, they are removed again (depending on the
5253 variable `cdlatex-simplify-sub-super-scripts').
5255 * Pressing the backquote ``' followed by a character inserts math
5256 macros, also outside LaTeX fragments. If you wait more than 1.5
5257 seconds after the backquote, a help window will pop up.
5259 * Pressing the normal quote `'' followed by another character
5260 modifies the symbol before point with an accent or a font. If you
5261 wait more than 1.5 seconds after the backquote, a help window will
5262 pop up. Character modification will work only inside LaTeX
5263 fragments, outside the quote is normal.
5265 ---------- Footnotes ----------
5267 (1) Org-mode has a method to test if the cursor is inside such a
5268 fragment, see the documentation of the function
5269 `org-inside-LaTeX-fragment-p'.
5272 File: org, Node: Exporting, Next: Publishing, Prev: Embedded LaTeX, Up: Top
5277 Org-mode documents can be exported into a variety of other formats. For
5278 printing and sharing of notes, ASCII export produces a readable and
5279 simple version of an Org-mode file. HTML export allows you to publish a
5280 notes file on the web, while the XOXO format provides a solid base for
5281 exchange with a broad range of other applications. LaTeX export lets
5282 you use Org-mode and its structured editing functions to easily create
5283 LaTeX files. To incorporate entries with associated times like
5284 deadlines or appointments into a desktop calendar program like iCal,
5285 Org-mode can also produce extracts in the iCalendar format. Currently
5286 Org-mode only supports export, not import of these different formats.
5288 When exporting, Org-mode uses special conventions to enrich the
5289 output produced. *Note Text interpretation::, for more details.
5292 Dispatcher for export and publishing commands. Displays a
5293 help-window listing the additional key(s) needed to launch an
5294 export or publishing command.
5298 * ASCII export:: Exporting to plain ASCII
5299 * HTML export:: Exporting to HTML
5300 * LaTeX export:: Exporting to LaTeX
5301 * XOXO export:: Exporting to XOXO
5302 * iCalendar export:: Exporting in iCalendar format
5303 * Text interpretation:: How the exporter looks at the file
5306 File: org, Node: ASCII export, Next: HTML export, Prev: Exporting, Up: Exporting
5311 ASCII export produces a simple and very readable version of an Org-mode
5315 Export as ASCII file. For an org file `myfile.org', the ASCII file
5316 will be `myfile.txt'. The file will be overwritten without
5317 warning. If there is an active region, only the region will be
5318 exported. If the selected region is a single tree, the tree head
5319 will become the document title. If the tree head entry has or
5320 inherits an EXPORT_FILE_NAME property, that name will be used for
5324 Export only the visible part of the document.
5326 In the exported version, the first 3 outline levels will become
5327 headlines, defining a general document structure. Additional levels
5328 will be exported as itemized lists. If you want that transition to
5329 occur at a different level, specify it with a prefix argument. For
5334 creates only top level headlines and does the rest as items. When
5335 headlines are converted to items, the indentation of the text following
5336 the headline is changed to fit nicely under the item. This is done with
5337 the assumption that the first bodyline indicates the base indentation of
5338 the body text. Any indentation larger than this is adjusted to preserve
5339 the layout relative to the first line. Should there be lines with less
5340 indentation than the first, these are left alone.
5343 File: org, Node: HTML export, Next: LaTeX export, Prev: ASCII export, Up: Exporting
5348 Org-mode contains an HTML (XHTML 1.0 strict) exporter with extensive
5349 HTML formatting, in ways similar to John Grubers _markdown_ language,
5350 but with additional support for tables.
5354 * HTML Export commands:: How to invoke LaTeX export
5355 * Quoting HTML tags:: Using direct HTML in Org-mode
5356 * Links:: Transformation of links for HTML
5357 * Images:: How to include images
5358 * CSS support:: Changing the appearence of the output
5361 File: org, Node: HTML Export commands, Next: Quoting HTML tags, Prev: HTML export, Up: HTML export
5363 12.2.1 HTML export commands
5364 ---------------------------
5367 Export as HTML file `myfile.html'. For an org file `myfile.org',
5368 the ASCII file will be `myfile.html'. The file will be
5369 overwritten without warning. If there is an active region, only
5370 the region will be exported. If the selected region is a single
5371 tree, the tree head will become the document title. If the tree
5372 head entry has or inherits an EXPORT_FILE_NAME property, that name
5373 will be used for the export.
5376 Export as HTML file and immediately open it with a browser.
5379 Export to a temporary buffer, do not create a file.
5382 Export the active region to a temporary buffer. With prefix arg,
5383 do not produce file header and foot, but just the plain HTML
5384 section for the region. This is good for cut-and-paste operations.
5393 Export only the visible part of the document.
5395 `M-x org-export-region-as-html'
5396 Convert the region to HTML under the assumption that it was
5397 org-mode syntax before. This is a global command that can be
5398 invoked in any buffer.
5400 `M-x org-replace-region-by-HTML'
5401 Replace the active region (assumed to be in Org-mode syntax) by
5404 In the exported version, the first 3 outline levels will become
5405 headlines, defining a general document structure. Additional levels
5406 will be exported as itemized lists. If you want that transition to
5407 occur at a different level, specify it with a prefix argument. For
5412 creates two levels of headings and does the rest as items.
5415 File: org, Node: Quoting HTML tags, Next: Links, Prev: HTML Export commands, Up: HTML export
5417 12.2.2 Quoting HTML tags
5418 ------------------------
5420 Plain `<' and `>' are always transformed to `<' and `>' in HTML
5421 export. If you want to include simple HTML tags which should be
5422 interpreted as such, mark them with `@' as in `@<b>bold text@</b>'.
5423 Note that this really works only for simple tags. For more extensive
5424 HTML that should be copied verbatim to the exported file use either
5426 #+HTML: Literal HTML code for export
5431 All lines between these markers are exported literally
5435 File: org, Node: Links, Next: Images, Prev: Quoting HTML tags, Up: HTML export
5440 Internal links (*note Internal links::) will continue to work in HTML
5441 files only if they match a dedicated `<<target>>'. Automatic links
5442 created by radio targets (*note Radio targets::) will also work in the
5443 HTML file. Links to external files will still work if the HTML file is
5444 in the same directory as the Org-mode file. Links to other `.org'
5445 files will be translated into HTML links under the assumption that an
5446 HTML version also exists of the linked file. For information related to
5447 linking files while publishing them to a publishing directory see *Note
5451 File: org, Node: Images, Next: CSS support, Prev: Links, Up: HTML export
5456 HTML export can inline images given as links in the Org-mode file, and
5457 it can make an image the clickable part of a link. By default(1),
5458 images are inlined if a link does not have a description. So
5459 `[[file:myimg.jpg]]' will be inlined, while `[[file:myimg.jpg][the
5460 image]]' will just produce a link `the image' that points to the image.
5461 If the description part itself is a `file:' link or a `http:' URL
5462 pointing to an image, this image will be inlined and activated so that
5463 clicking on the image will activate the link. For example, to include
5464 a thumbnail that will link to a high resolution version of the image,
5467 [[file:highres.jpg][file:thumb.jpg]]
5469 and you could use `http' addresses just as well.
5471 ---------- Footnotes ----------
5473 (1) but see the variable `org-export-html-inline-images'
5476 File: org, Node: CSS support, Prev: Images, Up: HTML export
5481 You can also give style information for the exported file. The HTML
5482 exporter assigns the following CSS classes to appropriate parts of the
5483 document - your style specifications may change these:
5485 .done the DONE keyword
5486 .timestamp time stamp
5487 .timestamp-kwd keyword associated with a time stamp, like SCHEDULED
5488 .tag tag in a headline
5489 .target target for links
5491 The default style specification can be configured through the option
5492 `org-export-html-style'. If you want to use a file-local style, you
5493 may use file variables, best wrapped into a COMMENT section at the end
5494 of the outline tree. For example(1):
5496 * COMMENT html style specifications
5499 # org-export-html-style: " <style type=\"text/css\">
5500 # p {font-weight: normal; color: gray; }
5501 # h1 {color: black; }
5505 Remember to execute `M-x normal-mode' after changing this to make
5506 the new style visible to Emacs. This command restarts org-mode for the
5507 current buffer and forces Emacs to re-evaluate the local variables
5508 section in the buffer.
5510 ---------- Footnotes ----------
5512 (1) Under Emacs 21, the continuation lines for a variable value
5513 should have no `#' at the start of the line.
5516 File: org, Node: LaTeX export, Next: XOXO export, Prev: HTML export, Up: Exporting
5521 Org-mode contains a LaTeX exporter written by Bastien Guerry.
5525 * LaTeX export commands:: How to invoke LaTeX export
5526 * Quoting LaTeX code:: Incorporating literal LaTeX code
5529 File: org, Node: LaTeX export commands, Next: Quoting LaTeX code, Prev: LaTeX export, Up: LaTeX export
5531 12.3.1 LaTeX export commands
5532 ----------------------------
5535 Export as LaTeX file `myfile.tex'.
5538 Export to a temporary buffer, do not create a file.
5543 Export only the visible part of the document.
5545 `M-x org-export-region-as-latex'
5546 Convert the region to LaTeX under the assumption that it was
5547 org-mode syntax before. This is a global command that can be
5548 invoked in any buffer.
5550 `M-x org-replace-region-by-latex'
5551 Replace the active region (assumed to be in Org-mode syntax) by
5554 In the exported version, the first 3 outline levels will become
5555 headlines, defining a general document structure. Additional levels
5556 will be exported as description lists. The exporter can ignore them or
5557 convert them to a custom string depending on `org-latex-low-levels'.
5559 If you want that transition to occur at a different level, specify it
5560 with a prefix argument. For example,
5564 creates two levels of headings and does the rest as items.
5567 File: org, Node: Quoting LaTeX code, Prev: LaTeX export commands, Up: LaTeX export
5569 12.3.2 Quoting LaTeX code
5570 -------------------------
5572 Embedded LaTeX as described in *Note Embedded LaTeX:: will be correctly
5573 inserted into the LaTeX file. Forthermore, you can add special code
5574 that should only be present in LaTeX export with the following
5577 #+LaTeX: Literal LaTeX code for export
5582 All lines between these markers are exported literally
5586 File: org, Node: XOXO export, Next: iCalendar export, Prev: LaTeX export, Up: Exporting
5591 Org-mode contains an exporter that produces XOXO-style output.
5592 Currently, this exporter only handles the general outline structure and
5593 does not interpret any additional Org-mode features.
5596 Export as XOXO file `myfile.html'.
5599 Export only the visible part of the document.
5602 File: org, Node: iCalendar export, Next: Text interpretation, Prev: XOXO export, Up: Exporting
5604 12.5 iCalendar export
5605 =====================
5607 Some people like to use Org-mode for keeping track of projects, but
5608 still prefer a standard calendar application for anniversaries and
5609 appointments. In this case it can be useful to have deadlines and
5610 other time-stamped items in Org-mode files show up in the calendar
5611 application. Org-mode can export calendar information in the standard
5612 iCalendar format. If you also want to have TODO entries included in the
5613 export, configure the variable `org-icalendar-include-todo'.
5616 Create iCalendar entries for the current file and store them in
5617 the same directory, using a file extension `.ics'.
5620 Like `C-c C-e i', but do this for all files in `org-agenda-files'.
5621 For each of these files, a separate iCalendar file will be
5625 Create a single large iCalendar file from all files in
5626 `org-agenda-files' and write it to the file given by
5627 `org-combined-agenda-icalendar-file'.
5629 How this calendar is best read and updated, depends on the
5630 application you are using. The FAQ covers this issue.
5633 File: org, Node: Text interpretation, Prev: iCalendar export, Up: Exporting
5635 12.6 Text interpretation by the exporter
5636 ========================================
5638 The exporter backends interpret additional structure in the Org-mode
5639 file in order to produce better output.
5643 * Comment lines:: Some lines will not be exported
5644 * Initial text:: Text before the first headline
5645 * Footnotes:: Numbers like [1]
5646 * Enhancing text:: Subscripts, symbols and more
5647 * Export options:: How to influence the export settings
5650 File: org, Node: Comment lines, Next: Initial text, Prev: Text interpretation, Up: Text interpretation
5652 12.6.1 Comment lines
5653 --------------------
5655 Lines starting with `#' in column zero are treated as comments and will
5656 never be exported. Also entire subtrees starting with the word
5657 `COMMENT' will never be exported.
5660 Toggle the COMMENT keyword at the beginning of an entry.
5663 File: org, Node: Initial text, Next: Footnotes, Prev: Comment lines, Up: Text interpretation
5665 12.6.2 Text before the first headline
5666 -------------------------------------
5668 Org-mode normally ignores any text before the first headline when
5669 exporting, leaving this region for internal links to speed up navigation
5670 etc. However, in publishing-oriented files, you might want to have some
5671 text before the first headline, like a small introduction, special HTML
5672 code with a navigation bar, etc. You can ask to have this part of the
5673 file exported as well by setting the variable
5674 `org-export-skip-text-before-1st-heading' to `nil'. On a per-file
5675 basis, you can get the same effect with
5679 The text before the first headline will be fully processed (*note
5680 Enhancing text::), and the first non-comment line becomes the title of
5681 the exported document. If you need to include literal HTML, use the
5682 special constructs described in *Note Quoting HTML tags::. The table
5683 of contents is normally inserted directly before the first headline of
5684 the file. If you would like to get it to a different location, insert
5685 the string `[TABLE-OF-CONTENTS]' on a line by itself at the desired
5688 Finally, if you want to use the space before the first headline for
5689 internal purposes, but _still_ want to place something before the first
5690 headline when exporting the file, you can use the `#+TEXT' construct:
5693 #+TEXT: This text will go before the *first* headline.
5694 #+TEXT: We place the table of contents here:
5695 #+TEXT: [TABLE-OF-CONTENTS]
5696 #+TEXT: This goes between the table of contents and the first headline
5699 File: org, Node: Footnotes, Next: Enhancing text, Prev: Initial text, Up: Text interpretation
5704 Numbers in square brackets are treated as footnotes, so that you can use
5705 the Emacs package `footnote.el' to create footnotes. For example:
5707 The org-mode homepage[1] clearly needs help from
5708 a good web designer.
5710 [1] The link is: http://orgmode.org
5712 Note that the `footnote' package uses `C-c !' to invoke its commands.
5713 This binding conflicts with the org-mode command for inserting inactive
5714 time stamps. You could use the variable `footnote-prefix' to switch
5715 footnotes commands to another key. Or, if you are too used to this
5716 binding, you could use `org-replace-disputed-keys' and
5717 `org-disputed-keys' to change the settings in Org-mode.
5720 File: org, Node: Enhancing text, Next: Export options, Prev: Footnotes, Up: Text interpretation
5722 12.6.4 Enhancing text for export
5723 --------------------------------
5725 Some of the export backends of Org-mode allow for sophisticated text
5726 formatting, this is true in particular for the HTML and LaTeX backends.
5727 Org-mode has a number of typing conventions that allow to produce a
5728 richly formatted output.
5730 * Plain lists `-', `*' or `+' as bullet, or with `1.' or `2)' as
5731 enumerator will be recognized and transformed if the backend
5732 supports lists. See *Note Plain lists::.
5734 * You can make words *bold*, /italic/, _underlined_, `=code=', and
5735 even `+strikethrough+'(1).
5737 * A line consisting of only dashes, and at least 5 of them, will be
5738 exported as a horizontal line (`<hr/>' in HTML).
5740 * Many TeX macros and entire LaTeX fragments are converted into HTML
5741 entities or images (*note Embedded LaTeX::).
5743 * Tables are transformed into native tables under the exporter, if
5744 the export backend supports this. Data fields before the first
5745 horizontal separator line will be formatted as table header fields.
5747 * If a headline starts with the word `QUOTE', the text below the
5748 headline will be typeset as fixed-width, to allow quoting of
5749 computer codes etc. Lines starting with `:' are also typeset in
5752 Toggle fixed-width for entry (QUOTE) or region, see below.
5754 * A double backslash _at the end of a line_ enforces a line break at
5757 If these conversions conflict with your habits of typing ASCII text,
5758 they can all be turned off with corresponding variables. See the
5759 customization group `org-export-general', and the following section
5760 which explains how to set export options with special lines in a buffer.
5762 ---------- Footnotes ----------
5764 (1) but remember that strikethrough is typographically evil and
5765 should never be used.
5768 File: org, Node: Export options, Prev: Enhancing text, Up: Text interpretation
5770 12.6.5 Export options
5771 ---------------------
5773 The exporter recognizes special lines in the buffer which provide
5774 additional information. These lines may be put anywhere in the file.
5775 The whole set of lines can be inserted into the buffer with `C-c C-e
5776 t'. For individual lines, a good way to make sure the keyword is
5777 correct is to type `#+' and then use `M-<TAB>' completion (*note
5781 Insert template with export options, see example below.
5783 #+TITLE: the title to be shown (default is the buffer name)
5784 #+AUTHOR: the author (default taken from `user-full-name')
5785 #+DATE: A date, fixed, of a format string for `format-time-string'
5786 #+EMAIL: his/her email address (default from `user-mail-address')
5787 #+LANGUAGE: language for HTML, e.g. `en' (`org-export-default-language')
5788 #+TEXT: Some descriptive text to be inserted at the beginning.
5789 #+TEXT: Several lines may be given.
5790 #+OPTIONS: H:2 num:t toc:t \n:nil @:t ::t |:t ^:t f:t TeX:t ...
5792 The OPTIONS line is a compact form to specify export settings. Here
5794 H: set the number of headline levels for export
5795 num: turn on/off section-numbers
5796 toc: turn on/off table of contents, or set level limit (integer)
5797 \n: turn on/off linebreak-preservation
5798 @: turn on/off quoted HTML tags
5799 :: turn on/off fixed-width sections
5800 |: turn on/off tables
5801 ^: turn on/off TeX-like syntax for sub- and superscripts. If
5802 you write "^:{}", `a_{b}' will be interpreted, but
5803 the simple `a_b' will be left as it is.
5804 f: turn on/off foototes like this[1].
5805 *: turn on/off emphasized text (bold, italic, underlined)
5806 TeX: turn on/off simple TeX macros in plain text
5807 LaTeX: turn on/off LaTeX fragments
5808 skip: turn on/off skipping the text before the first heading
5809 author: turn on/off inclusion of author name/email into exported file
5810 timestamp: turn on/off inclusion creation time into exported file
5812 These options take effect in both the HTML and LaTeX export, except
5813 for `TeX' and `LaTeX', which are respectively `t' and `nil' for the
5817 File: org, Node: Publishing, Next: Miscellaneous, Prev: Exporting, Up: Top
5822 Org-mode includes(1) a publishing management system that allows you to
5823 configure automatic HTML conversion of _projects_ composed of
5824 interlinked org files. This system is called _org-publish_. You can
5825 also configure org-publish to automatically upload your exported HTML
5826 pages and related attachments, such as images and source code files, to
5827 a web server. Org-publish turns org-mode into a web-site authoring tool.
5829 You can also use Org-publish to convert files into LaTeX, or even
5830 combine HTML and LaTeX conversion so that files are available in both
5831 formats on the server(2).
5833 Org-publish has been contributed to Org-mode by David O'Toole.
5837 * Configuration:: Defining projects
5838 * Sample configuration:: Example projects
5839 * Triggering publication:: Publication commands
5841 ---------- Footnotes ----------
5843 (1) `org-publish.el' is not distributed with Emacs 21, if you are
5844 still using Emacs 21, you need you need to download this file
5847 (2) Since LaTeX files on a server are not that helpful, you surely
5848 want to perform further conversion on them - e.g. convert them to `PDF'
5852 File: org, Node: Configuration, Next: Sample configuration, Prev: Publishing, Up: Publishing
5857 Publishing needs significant configuration to specify files, destination
5858 and many other properties of a project.
5862 * Project alist:: The central configuration variable
5863 * Sources and destinations:: From here to there
5864 * Selecting files:: What files are part of the project?
5865 * Publishing action:: Setting the function doing the publishing
5866 * Publishing options:: Tweaking HTML export
5867 * Publishing links:: Which links keep working after publishing?
5868 * Project page index:: Publishing a list of project files
5871 File: org, Node: Project alist, Next: Sources and destinations, Prev: Configuration, Up: Configuration
5873 13.1.1 The variable `org-publish-project-alist'
5874 -----------------------------------------------
5876 Org-publish is configured almost entirely through setting the value of
5877 one variable, called `org-publish-project-alist'. Each element of the
5878 list configures one project, and may be in one of the two following
5881 ("project-name" :property value :property value ...)
5885 ("project-name" :components ("project-name" "project-name" ...))
5887 In both cases, projects are configured by specifying property values.
5888 A project defines the set of files that will be published, as well as
5889 the publishing configuration to use when publishing those files. When
5890 a project takes the second form listed above, the individual members of
5891 the "components" property are taken to be components of the project,
5892 which group together files requiring different publishing options. When
5893 you publish such a "meta-project" all the components will also publish.
5896 File: org, Node: Sources and destinations, Next: Selecting files, Prev: Project alist, Up: Configuration
5898 13.1.2 Sources and destinations for files
5899 -----------------------------------------
5901 Most properties are optional, but some should always be set. In
5902 particular, org-publish needs to know where to look for source files,
5903 and where to put published files.
5905 `:base-directory' Directory containing publishing source files
5906 `:publishing-directory'Directory (possibly remote) where output files
5908 `:preparation-function'Function called before starting publishing
5909 process, for example to run `make' for updating
5910 files to be published.
5913 File: org, Node: Selecting files, Next: Publishing action, Prev: Sources and destinations, Up: Configuration
5915 13.1.3 Selecting files
5916 ----------------------
5918 By default, all files with extension `.org' in the base directory are
5919 considered part of the project. This can be modified by setting the
5921 `:base-extension' Extension (without the dot!) of source files. This
5922 actually is a regular expression.
5923 `:exclude' Regular expression to match file names that should
5924 not be published, even though they have been selected
5925 on the basis of their extension.
5926 `:include' List of files to be included regardless of
5927 `:base-extension' and `:exclude'.
5930 File: org, Node: Publishing action, Next: Publishing options, Prev: Selecting files, Up: Configuration
5932 13.1.4 Publishing Action
5933 ------------------------
5935 Publishing means that a file is copied to the destination directory and
5936 possibly transformed in the process. The default transformation is to
5937 export Org-mode files as HTML files, and this is done by the function
5938 `org-publish-org-to-html' which calls the HTML exporter (*note HTML
5939 export::). But you also can publish your files in LaTeX by using the
5940 function `org-publish-org-to-latex' instead. Other files like images
5941 only need to be copied to the publishing destination. For non-Org-mode
5942 files, you need to specify the publishing function.
5944 `:publishing-function' Function executing the publication of a file.
5945 This may also be a list of functions, which will
5946 all be called in turn.
5948 The function must accept two arguments: a property list containing at
5949 least a `:publishing-directory' property, and the name of the file to
5950 be published. It should take the specified file, make the necessary
5951 transformation (if any) and place the result into the destination
5952 folder. You can write your own publishing function, but `org-publish'
5953 provides one for attachments (files that only need to be copied):
5954 `org-publish-attachment'.
5957 File: org, Node: Publishing options, Next: Publishing links, Prev: Publishing action, Up: Configuration
5959 13.1.5 Options for the HTML/LaTeX exporters
5960 -------------------------------------------
5962 The property list can be used to set many export options for the HTML
5963 and LaTeX exporters. In most cases, these properties correspond to user
5964 variables in Org-mode. The table below lists these properties along
5965 with the variable they belong to. See the documentation string for the
5966 respective variable for details.
5968 `:language' `org-export-default-language'
5969 `:headline-levels' `org-export-headline-levels'
5970 `:section-numbers' `org-export-with-section-numbers'
5971 `:table-of-contents' `org-export-with-toc'
5972 `:archived-trees' `org-export-with-archived-trees'
5973 `:emphasize' `org-export-with-emphasize'
5974 `:sub-superscript' `org-export-with-sub-superscripts'
5975 `:TeX-macros' `org-export-with-TeX-macros'
5976 `:LaTeX-fragments' `org-export-with-LaTeX-fragments'
5977 `:fixed-width' `org-export-with-fixed-width'
5978 `:timestamps' `org-export-with-timestamps'
5980 `:tags' `org-export-with-tags'
5982 `:tables' `org-export-with-tables'
5983 `:table-auto-headline' `org-export-highlight-first-table-line'
5984 `:style' `org-export-html-style'
5985 `:convert-org-links' `org-export-html-link-org-files-as-html'
5986 `:inline-images' `org-export-html-inline-images'
5987 `:expand-quoted-html' `org-export-html-expand'
5988 `:timestamp' `org-export-html-with-timestamp'
5989 `:publishing-directory'`org-export-publishing-directory'
5990 `:preamble' `org-export-html-preamble'
5991 `:postamble' `org-export-html-postamble'
5992 `:auto-preamble' `org-export-html-auto-preamble'
5993 `:auto-postamble' `org-export-html-auto-postamble'
5994 `:author' `user-full-name'
5995 `:email' `user-mail-address'
5997 Most of the `org-export-with-*' variables have the same effect in
5998 both HTML and LaTeX exporters, except for `:TeX-macros' and
5999 `:LaTeX-fragments', respectively `nil' and `t' in the LaTeX export.
6001 When a property is given a value in org-publish-project-alist, its
6002 setting overrides the value of the corresponding user variable (if any)
6003 during publishing. Options set within a file (*note Export options::),
6004 however, override everything.
6007 File: org, Node: Publishing links, Next: Project page index, Prev: Publishing options, Up: Configuration
6009 13.1.6 Links between published files
6010 ------------------------------------
6012 To create a link from one Org-mode file to another, you would use
6013 something like `[[file:foo.org][The foo]]' or simply `file:foo.org.'
6014 (*note Hyperlinks::). Upon publishing this link becomes a link to
6015 `foo.html'. In this way, you can interlink the pages of your "org web"
6016 project and the links will work as expected when you publish them to
6019 You may also link to related files, such as images. Provided you are
6020 careful with relative pathnames, and provided you have also configured
6021 org-publish to upload the related files, these links will work too.
6022 *Note Complex example:: for an example of this usage.
6024 Sometime an Org-mode file to be published may contain links that are
6025 only valid in your production environment, but not in the publishing
6026 location. In this case, use the property
6028 `:link-validation-function' Function to validate links
6030 to define a function for checking link validity. This function must
6031 accept two arguments, the file name and a directory relative to which
6032 the file name is interpreted in the production environment. If this
6033 function returns `nil', then the HTML generator will only insert a
6034 description into the HTML file, but no link. One option for this
6035 function is `org-publish-validate-link' which checks if the given file
6036 is part of any project in `org-publish-project-alist'.
6039 File: org, Node: Project page index, Prev: Publishing links, Up: Configuration
6041 13.1.7 Project page index
6042 -------------------------
6044 The following properties may be used to control publishing of an index
6045 of files or summary page for a given project.
6047 `:auto-index' When non-nil, publish an index during
6048 org-publish-current-project or org-publish-all.
6049 `:index-filename' Filename for output of index. Defaults to `index.org'
6050 (which becomes `index.html').
6051 `:index-title' Title of index page. Defaults to name of file.
6052 `:index-function' Plugin function to use for generation of index.
6053 Defaults to `org-publish-org-index', which generates
6054 a plain list of links to all files in the project.
6057 File: org, Node: Sample configuration, Next: Triggering publication, Prev: Configuration, Up: Publishing
6059 13.2 Sample configuration
6060 =========================
6062 Below we provide two example configurations. The first one is a simple
6063 project publishing only a set of Org-mode files. The second example is
6064 more complex, with a multi-component project.
6068 * Simple example:: One-component publishing
6069 * Complex example:: A multi-component publishing example
6072 File: org, Node: Simple example, Next: Complex example, Prev: Sample configuration, Up: Sample configuration
6074 13.2.1 Example: simple publishing configuration
6075 -----------------------------------------------
6077 This example publishes a set of Org-mode files to the `public_html'
6078 directory on the local machine.
6080 (setq org-publish-project-alist
6082 :base-directory "~/org/"
6083 :publishing-directory "~/public_html"
6084 :section-numbers nil
6085 :table-of-contents nil
6086 :style "<link rel=stylesheet
6087 href=\"../other/mystyle.css\"
6088 type=\"text/css\">")))
6091 File: org, Node: Complex example, Prev: Simple example, Up: Sample configuration
6093 13.2.2 Example: complex publishing configuration
6094 ------------------------------------------------
6096 This more complicated example publishes an entire website, including
6097 org files converted to HTML, image files, emacs lisp source code, and
6098 stylesheets. The publishing-directory is remote and private files are
6101 To ensure that links are preserved, care should be taken to replicate
6102 your directory structure on the web server, and to use relative file
6103 paths. For example, if your org files are kept in `~/org' and your
6104 publishable images in `~/images', you'd link to an image with
6105 file:../images/myimage.png
6106 On the web server, the relative path to the image should be the
6107 same. You can accomplish this by setting up an "images" folder in the
6108 right place on the webserver, and publishing images to it.
6110 (setq org-publish-project-alist
6112 :base-directory "~/org/"
6113 :base-extension "org"
6114 :publishing-directory "/ssh:user@host:~/html/notebook/"
6115 :publishing-function org-publish-org-to-html
6116 :exclude "PrivatePage.org" ;; regexp
6118 :section-numbers nil
6119 :table-of-contents nil
6120 :style "<link rel=stylesheet
6121 href=\"../other/mystyle.css\" type=\"text/css\">"
6123 :auto-postamble nil)
6126 :base-directory "~/images/"
6127 :base-extension "jpg\\|gif\\|png"
6128 :publishing-directory "/ssh:user@host:~/html/images/"
6129 :publishing-function org-publish-attachment)
6132 :base-directory "~/other/"
6133 :base-extension "css\\|el"
6134 :publishing-directory "/ssh:user@host:~/html/other/"
6135 :publishing-function org-publish-attachment)
6136 ("website" :components ("orgfiles" "images" "other"))))
6139 File: org, Node: Triggering publication, Prev: Sample configuration, Up: Publishing
6141 13.3 Triggering publication
6142 ===========================
6144 Once org-publish is properly configured, you can publish with the
6145 following functions:
6148 Prompt for a specific project and publish all files that belong to
6152 Publish the project containing the current file.
6155 Publish only the current file.
6158 Publish all projects.
6160 Org uses timestamps to track when a file has changed. The above
6161 functions normally only publish changed files. You can override this and
6162 force publishing of all files by giving a prefix argument.
6165 File: org, Node: Miscellaneous, Next: Extensions and Hacking, Prev: Publishing, Up: Top
6172 * Completion:: M-TAB knows what you need
6173 * Customization:: Adapting Org-mode to your taste
6174 * In-buffer settings:: Overview of the #+KEYWORDS
6175 * The very busy C-c C-c key:: When in doubt, press C-c C-c
6176 * Clean view:: Getting rid of leading stars in the outline
6177 * TTY keys:: Using Org-mode on a tty
6178 * Interaction:: Other Emacs packages
6179 * Bugs:: Things which do not work perfectly
6182 File: org, Node: Completion, Next: Customization, Prev: Miscellaneous, Up: Miscellaneous
6187 Org-mode supports in-buffer completion. This type of completion does
6188 not make use of the minibuffer. You simply type a few letters into the
6189 buffer and use the key to complete text right there.
6192 Complete word at point
6193 * At the beginning of a headline, complete TODO keywords.
6195 * After `\', complete TeX symbols supported by the exporter.
6197 * After `*', complete headlines in the current buffer so that
6198 they can be used in search links like `[[*find this
6201 * After `:' in a headline, complete tags. The list of tags is
6202 taken from the variable `org-tag-alist' (possibly set through
6203 the `#+TAGS' in-buffer option, *note Setting tags::), or it
6204 is created dynamically from all tags used in the current
6207 * After `:' and not in a headline, complete property keys. The
6208 list of keys is constructed dynamically from all keys used in
6211 * After `[', complete link abbreviations (*note Link
6214 * After `#+', complete the special keywords like `TYP_TODO' or
6215 `OPTIONS' which set file-specific options for Org-mode. When
6216 the option keyword is already complete, pressing `M-<TAB>'
6217 again will insert example settings for this keyword.
6219 * In the line after `#+STARTUP: ', complete startup keywords,
6220 i.e. valid keys for this line.
6222 * Elsewhere, complete dictionary words using ispell.
6225 File: org, Node: Customization, Next: In-buffer settings, Prev: Completion, Up: Miscellaneous
6230 There are more than 180 variables that can be used to customize
6231 Org-mode. For the sake of compactness of the manual, I am not
6232 describing the variables here. A structured overview of customization
6233 variables is available with `M-x org-customize'. Or select `Browse Org
6234 Group' from the `Org->Customization' menu. Many settings can also be
6235 activated on a per-file basis, by putting special lines into the buffer
6236 (*note In-buffer settings::).
6239 File: org, Node: In-buffer settings, Next: The very busy C-c C-c key, Prev: Customization, Up: Miscellaneous
6241 14.3 Summary of in-buffer settings
6242 ==================================
6244 Org-mode uses special lines in the buffer to define settings on a
6245 per-file basis. These lines start with a `#+' followed by a keyword, a
6246 colon, and then individual words defining a setting. Several setting
6247 words can be in the same line, but you can also have multiple lines for
6248 the keyword. While these settings are described throughout the manual,
6249 here is a summary. After changing any of those lines in the buffer,
6250 press `C-c C-c' with the cursor still in the line to activate the
6251 changes immediately. Otherwise they become effective only when the
6252 file is visited again in a new Emacs session.
6254 `#+ARCHIVE: %s_done::'
6255 This line sets the archive location for the agenda file. It
6256 applies for all subsequent lines until the next `#+ARCHIVE' line,
6257 or the end of the file. The first such line also applies to any
6258 entries before it. The corresponding variable is
6259 `org-archive-location'.
6262 This line sets the category for the agenda file. The category
6263 applies for all subsequent lines until the next `#+CATEGORY' line,
6264 or the end of the file. The first such line also applies to any
6267 `#+COLUMNS: %25ITEM .....'
6268 Set the default format for columns view. This format applies when
6269 columns view is invoked in location where no COLUMNS property
6272 `#+CONSTANTS: name1=value1 ...'
6273 Set file-local values for constants to be used in table formulas.
6274 This line set the local variable
6275 `org-table-formula-constants-local'. The global version of theis
6276 variable is `org-table-formula-constants'. corresponding
6278 `#+LINK: linkword replace'
6279 These lines (several are allowed) specify link abbreviations.
6280 *Note Link abbreviations::. The corresponding variable is
6281 `org-link-abbrev-alist'.
6283 `#+PRIORITIES: highest lowest default'
6284 This line sets the limits and the default for the priorities. All
6285 three must be either letters A-Z or numbers 0-9. The highest
6286 priority must have a lower ASCII number that the lowest priority.
6288 `#+PROPERTY: Property_Name Value'
6289 This line sets a default inheritance value for entries in the
6290 current buffer, most useful for specifying the allowed values of a
6294 This line sets options to be used at startup of Org-mode, when an
6295 Org-mode file is being visited. The first set of options deals
6296 with the initial visibility of the outline tree. The
6297 corresponding variable for global default settings is
6298 `org-startup-folded', with a default value `t', which means
6300 overview top-level headlines only
6301 content all headlines
6302 showall no folding at all, show everything
6303 Then there are options for aligning tables upon visiting a file.
6304 This is useful in files containing narrowed table columns. The
6305 corresponding variable is `org-startup-align-all-tables', with a
6306 default value `nil'.
6307 align align all tables
6308 noalign don't align tables on startup
6309 Logging TODO state changes and clock intervals (variable
6310 `org-log-done') can be configured using these options.
6311 logging record a timestamp when an item is marked DONE
6312 nologging don't record when items are marked DONE
6313 lognotedone record timestamp and a note when DONE
6314 lognotestate record timestamp and a note when TODO state changes
6315 logrepeat record a note when re-instating a repeating item
6316 nologrepeat do not record when re-instating repeating item
6317 lognoteclock-out record timestamp and a note when clocking out
6318 Here are the options for hiding leading stars in outline headings.
6319 The corresponding variables are `org-hide-leading-stars' and
6320 `org-odd-levels-only', both with a default setting `nil' (meaning
6321 `showstars' and `oddeven').
6322 hidestars make all but one of the stars starting a headline invisible.
6323 showstars show all stars starting a headline
6324 odd allow only odd outline levels (1,3,...)
6325 oddeven allow all outline levels
6326 To turn on custom format overlays over time stamps (variables
6327 `org-put-time-stamp-overlays' and
6328 `org-time-stamp-overlay-formats'), use
6329 customtime overlay custom time format
6330 The following options influence the table spreadsheet (variable
6331 `constants-unit-system').
6332 constcgs `constants.el' should use the c-g-s unit system
6333 constSI `constants.el' should use the SI unit system
6335 `#+TAGS: TAG1(c1) TAG2(c2)'
6336 These lines (several such lines are allowed) specify the legal
6337 tags in this file, and (potentially) the corresponding _fast tag
6338 selection_ keys. The corresponding variable is `org-tag-alist'.
6341 This line contains the formulas for the table directly above the
6344 `#+TITLE:, #+AUTHOR:, #+EMAIL:, #+LANGUAGE:, #+TEXT:, #+OPTIONS, #+DATE:'
6345 These lines provide settings for exporting files. For more
6346 details see *Note Export options::.
6348 `#+SEQ_TODO: #+TYP_TODO:'
6349 These lines set the TODO keywords and their interpretation in the
6350 current file. The corresponding variables are `org-todo-keywords'
6351 and `org-todo-interpretation'.
6354 File: org, Node: The very busy C-c C-c key, Next: Clean view, Prev: In-buffer settings, Up: Miscellaneous
6356 14.4 The very busy C-c C-c key
6357 ==============================
6359 The key `C-c C-c' has many purposes in org-mode, which are all
6360 mentioned scattered throughout this manual. One specific function of
6361 this key is to add _tags_ to a headline (*note Tags::). In many other
6362 circumstances it means something like _Hey Org-mode, look here and
6363 update according to what you see here_. Here is a summary of what this
6364 means in different contexts.
6366 - If there are highlights in the buffer from the creation of a sparse
6367 tree, or from clock display, remove these highlights.
6369 - If the cursor is in one of the special `#+KEYWORD' lines, this
6370 triggers scanning the buffer for these lines and updating the
6373 - If the cursor is inside a table, realign the table. This command
6374 works even if the automatic table editor has been turned off.
6376 - If the cursor is on a `#+TBLFM' line, re-apply the formulas to the
6379 - If the cursor is inside a table created by the `table.el' package,
6380 activate that table.
6382 - If the current buffer is a remember buffer, close the note and
6383 file it. With a prefix argument, file it, without further
6384 interaction, to the default location.
6386 - If the cursor is on a `<<<target>>>', update radio targets and
6387 corresponding links in this buffer.
6389 - If the cursor is in a property line or at the start or end of a
6390 property drawer, offer property commands.
6392 - If the cursor is in a plain list item with a checkbox, toggle the
6393 status of the checkbox.
6395 - If the cursor is on a numbered item in a plain list, renumber the
6398 - If the cursor is on the `#+BEGIN' line of a dynamical block, the
6402 File: org, Node: Clean view, Next: TTY keys, Prev: The very busy C-c C-c key, Up: Miscellaneous
6404 14.5 A cleaner outline view
6405 ===========================
6407 Some people find it noisy and distracting that the Org-mode headlines
6408 are starting with a potentially large number of stars. For example the
6409 tree from *Note Headlines:::
6411 * Top level headline
6417 * Another top level headline
6419 Unfortunately this is deeply ingrained into the code of Org-mode and
6420 cannot be easily changed. You can, however, modify the display in such
6421 a way that all leading stars become invisible and the outline more easy
6422 to read. To do this, customize the variable `org-hide-leading-stars'
6425 (setq org-hide-leading-stars t)
6427 or change this on a per-file basis with one of the lines (anywhere in
6430 #+STARTUP: showstars
6431 #+STARTUP: hidestars
6433 Press `C-c C-c' with the cursor in a `STARTUP' line to activate the
6436 With stars hidden, the tree becomes:
6438 * Top level headline
6444 * Another top level headline
6446 Note that the leading stars are not truly replaced by whitespace, they
6447 are only fontified with the face `org-hide' that uses the background
6448 color as font color. If you are not using either white or black
6449 background, you may have to customize this face to get the wanted
6450 effect. Another possibility is to set this font such that the extra
6451 stars are almost invisible, for example using the color `grey90' on a
6454 Things become cleaner still if you skip all the even levels and use
6455 only odd levels 1, 3, 5..., effectively adding two stars to go from one
6456 outline level to the next:
6458 * Top level headline
6464 * Another top level headline
6466 In order to make the structure editing and export commands handle this
6467 convention correctly, use
6469 (setq org-odd-levels-only t)
6471 or set this on a per-file basis with one of the following lines (don't
6472 forget to press `C-c C-c' with the cursor in the startup line to
6473 activate changes immediately).
6478 You can convert an Org-mode file from single-star-per-level to the
6479 double-star-per-level convention with `M-x org-convert-to-odd-levels
6480 RET' in that file. The reverse operation is `M-x
6481 org-convert-to-oddeven-levels'.
6484 File: org, Node: TTY keys, Next: Interaction, Prev: Clean view, Up: Miscellaneous
6486 14.6 Using org-mode on a tty
6487 ============================
6489 Org-mode uses a number of keys that are not accessible on a tty. This
6490 applies to most special keys like cursor keys, <TAB> and <RET>, when
6491 these are combined with modifier keys like <Meta> and/or <Shift>.
6492 Org-mode uses these bindings because it needs to provide keys for a
6493 large number of commands, and because these keys appeared particularly
6494 easy to remember. In order to still be able to access the core
6495 functionality of Org-mode on a tty, alternative bindings are provided.
6496 Here is a complete list of these bindings, which are obviously more
6497 cumbersome to use. Note that sometimes a work-around can be better.
6498 For example changing a time stamp is really only fun with `S-<cursor>'
6499 keys. On a tty you would rather use `C-c .' to re-insert the
6502 Default Alternative 1 Alternative 2
6503 `S-<TAB>' `C-u <TAB>'
6504 `M-<left>' `C-c C-x l' `<Esc> <left>'
6505 `M-S-<left>'`C-c C-x L'
6506 `M-<right>' `C-c C-x r' `<Esc>
6508 `M-S-<right>'`C-c C-x R'
6509 `M-<up>' `C-c C-x u' `<Esc> <up>'
6510 `M-S-<up>' `C-c C-x U'
6511 `M-<down>' `C-c C-x d' `<Esc> <down>'
6512 `M-S-<down>'`C-c C-x D'
6513 `S-<RET>' `C-c C-x c'
6514 `M-<RET>' `C-c C-x m' `<Esc> <RET>'
6515 `M-S-<RET>' `C-c C-x M'
6516 `S-<left>' `C-c <left>'
6517 `S-<right>' `C-c <right>'
6519 `S-<down>' `C-c <down>'
6520 `C-S-<left>'`C-c C-x
6522 `C-S-<right>'`C-c C-x
6526 File: org, Node: Interaction, Next: Bugs, Prev: TTY keys, Up: Miscellaneous
6528 14.7 Interaction with other packages
6529 ====================================
6531 Org-mode lives in the world of GNU Emacs and interacts in various ways
6532 with other code out there.
6536 * Cooperation:: Packages Org-mode cooperates with
6537 * Conflicts:: Packages that lead to conflicts
6540 File: org, Node: Cooperation, Next: Conflicts, Prev: Interaction, Up: Interaction
6542 14.7.1 Packages that Org-mode cooperates with
6543 ---------------------------------------------
6545 `calc.el' by Dave Gillespie
6546 Org-mode uses the calc package for implementing spreadsheet
6547 functionality in its tables (*note The spreadsheet::). Org-mode
6548 checks for the availability of calc by looking for the function
6549 `calc-eval' which should be autoloaded in your setup if calc has
6550 been installed properly. As of Emacs 22, calc is part of the Emacs
6551 distribution. Another possibility for interaction between the two
6552 packages is using calc for embedded calculations. *Note Embedded
6553 Mode: (calc)Embedded Mode.
6555 `constants.el' by Carsten Dominik
6556 In a table formula (*note The spreadsheet::), it is possible to use
6557 names for natural constants or units. Instead of defining your own
6558 constants in the variable `org-table-formula-constants', install
6559 the `constants' package which defines a large number of constants
6560 and units, and lets you use unit prefixes like `M' for `Mega' etc.
6561 You will need version 2.0 of this package, available at
6562 `http://www.astro.uva.nl/~dominik/Tools'. Org-mode checks for the
6563 function `constants-get', which has to be autoloaded in your
6564 setup. See the installation instructions in the file
6567 `cdlatex.el' by Carsten Dominik
6568 Org-mode can make use of the cdlatex package to efficiently enter
6569 LaTeX fragments into Org-mode files. See *Note CDLaTeX mode::.
6571 `remember.el' by John Wiegley
6572 Org mode cooperates with remember, see *Note Remember::.
6573 `Remember.el' is not part of Emacs, find it on the web.
6575 `table.el' by Takaaki Ota
6576 Complex ASCII tables with automatic line wrapping, column- and
6577 row-spanning, and alignment can be created using the Emacs table
6578 package by Takaaki Ota (`http://sourceforge.net/projects/table',
6579 and also part of Emacs 22). When <TAB> or `C-c C-c' is pressed in
6580 such a table, Org-mode will call `table-recognize-table' and move
6581 the cursor into the table. Inside a table, the keymap of Org-mode
6582 is inactive. In order to execute Org-mode-related commands, leave
6586 Recognize `table.el' table. Works when the cursor is in a
6590 Insert a table.el table. If there is already a table at
6591 point, this command converts it between the table.el format
6592 and the Org-mode format. See the documentation string of the
6593 command `org-convert-table' for the restrictions under which
6595 `table.el' is part of Emacs 22.
6597 `footnote.el' by Steven L. Baur
6598 Org-mode recognizes numerical footnotes as provided by this package
6599 (*note Footnotes::).
6602 File: org, Node: Conflicts, Prev: Cooperation, Up: Interaction
6604 14.7.2 Packages that lead to conflicts with Org-mode
6605 ----------------------------------------------------
6607 `allout.el' by Ken Manheimer
6608 Startup of Org-mode may fail with the error message
6609 `(wrong-type-argument keymapp nil)' when there is an outdated
6610 version `allout.el' on the load path, for example the version
6611 distributed with Emacs 21.x. Upgrade to Emacs 22 and this problem
6612 will disappear. If for some reason you cannot do this, make sure
6613 that org.el is loaded _before_ `allout.el', for example by putting
6614 `(require 'org)' early enough into your `.emacs' file.
6616 `CUA.el' by Kim. F. Storm
6617 Keybindings in Org-mode conflict with the `S-<cursor>' keys used
6618 by CUA-mode (as well as pc-select-mode and s-region-mode) to
6619 select and extend the region. If you want to use one of these
6620 packages along with Org-mode, configure the variable
6621 `org-CUA-compatible'. When set, Org-mode will move the following
6622 keybindings in Org-mode files, and in the agenda buffer (but not
6623 during date selection).
6625 S-UP -> M-p S-DOWN -> M-n
6626 S-LEFT -> M-- S-RIGHT -> M-+
6628 Yes, these are unfortunately more difficult to remember. If you
6629 want to have other replacement keys, look at the variable
6630 `org-disputed-keys'.
6632 `windmove.el' by Hovav Shacham
6633 Also this package uses the `S-<cursor>' keys, so everything written
6634 in the paragraph above about CUA mode also applies here.
6636 `footnote.el' by Steven L. Baur
6637 Org-mode supports the syntax of the footnote package, but only the
6638 numerical footnote markers. Also, the default key for footnote
6639 commands, `C-c !' is already used by Org-mode. You could use the
6640 variable `footnote-prefix' to switch footnotes commands to another
6641 key. Or, you could use `org-replace-disputed-keys' and
6642 `org-disputed-keys' to change the settings in Org-mode.
6646 File: org, Node: Bugs, Prev: Interaction, Up: Miscellaneous
6651 Here is a list of things that should work differently, but which I have
6652 found too hard to fix.
6654 * If a table field starts with a link, and if the corresponding table
6655 column is narrowed (*note Narrow columns::) to a width too small to
6656 display the link, the field would look entirely empty even though
6657 it is not. To prevent this, Org-mode throws an error. The
6658 work-around is to make the column wide enough to fit the link, or
6659 to add some text (at least 2 characters) before the link in the
6662 * Narrowing table columns does not work on XEmacs, because the
6663 `format' function does not transport text properties.
6665 * Text in an entry protected with the `QUOTE' keyword should not
6668 * When the application called by `C-c C-o' to open a file link fails
6669 (for example because the application does not exist or refuses to
6670 open the file), it does so silently. No error message is
6673 * Recalculating a table line applies the formulas from left to right.
6674 If a formula uses _calculated_ fields further down the row,
6675 multiple recalculation may be needed to get all fields consistent.
6676 You may use the command `org-table-iterate' (`C-u C-c *') to
6677 recalculate until convergence.
6679 * A single letter cannot be made bold, for example `*a*'.
6681 * The exporters work well, but could be made more efficient.
6684 File: org, Node: Extensions and Hacking, Next: History and Acknowledgments, Prev: Miscellaneous, Up: Top
6686 Appendix A Extensions, Hooks and Hacking
6687 ****************************************
6689 This appendix lists extensions for Org-mode written by other authors.
6690 It also covers some aspects where users can extend the functionality of
6695 * Extensions:: Existing 3rd-part extensions
6696 * Adding hyperlink types:: New custom link types
6697 * Tables in arbitrary syntax:: Orgtbl for LaTeX and other programs
6698 * Dynamic blocks:: Automatically filled blocks
6699 * Special agenda views:: Customized views
6700 * Using the property API:: Writing programs that use entry properties
6703 File: org, Node: Extensions, Next: Adding hyperlink types, Prev: Extensions and Hacking, Up: Extensions and Hacking
6705 A.1 Third-party extensions for Org-mode
6706 =======================================
6708 The following extensions for Org-mode have been written by other people:
6710 `org-publish.el' by David O'Toole
6711 This package provides facilities for publishing related sets of
6712 Org-mode files together with linked files like images as webpages.
6713 It is highly configurable and can be used for other publishing
6714 purposes as well. As of Org-mode version 4.30, `org-publish.el'
6715 is part of the Org-mode distribution. It is not yet part of
6716 Emacs, however, a delay caused by the preparations for the 22.1
6717 release. In the mean time, `org-publish.el' can be downloaded
6718 from David's site: `http://dto.freeshell.org/e/org-publish.el'.
6720 `org-mouse.el' by Piotr Zielinski
6721 This package implements extended mouse functionality for Org-mode.
6722 It allows you to cycle visibility and to edit the document
6723 structure with the mouse. Best of all, it provides a
6724 context-sensitive menu on <mouse-3> that changes depending on the
6725 context of a mouse-click. As of Org-mode version 4.53,
6726 `org-mouse.el' is part of the Org-mode distribution. It is not
6727 yet part of Emacs, however, a delay caused by the preparations for
6728 the 22.1 release. In the mean time, `org-mouse.el' can be
6729 downloaded from Piotr's site:
6730 `http://www.cl.cam.ac.uk/~pz215/files/org-mouse.el'.
6732 `org-blog.el' by David O'Toole
6733 A blogging plug-in for `org-publish.el'.
6734 `http://dto.freeshell.org/notebook/OrgMode.html'.
6736 `blorg.el' by Bastien Guerry
6737 Publish Org-mode files as blogs.
6738 `http://www.cognition.ens.fr/~guerry/blorg.html'.
6740 `org2rem.el' by Bastien Guerry
6741 Translates Org-mode files into something readable by Remind.
6742 `http://www.cognition.ens.fr/~guerry/u/org2rem.el'.
6744 `org-toc.el' by Bastien Guerry
6745 Produces a simple table of contents of an Org-mode file, for easy
6746 navigation. `http://www.cognition.ens.fr/~guerry/u/org2rem.el'.
6748 `org-registry.el' by Bastien Guerry
6749 Find which Org-file link to a certain document.
6750 `http://www.cognition.ens.fr/~guerry/u/org2rem.el'.
6753 File: org, Node: Adding hyperlink types, Next: Tables in arbitrary syntax, Prev: Extensions, Up: Extensions and Hacking
6755 A.2 Adding hyperlink types
6756 ==========================
6758 Org-mode has a large number of hyperlink types built-in (*note
6759 Hyperlinks::). If you would like to add new link types, it provides an
6760 interface for doing so. Lets look at an example file `org-man.el' that
6761 will add support for creating links like `[[man:printf][The printf
6762 manpage]]' to show unix manual pages inside emacs:
6764 ;;; org-man.el - Support for links to manpages in Org-mode
6768 (org-add-link-type "man" 'org-man-open)
6769 (add-hook 'org-store-link-functions 'org-man-store-link)
6771 (defcustom org-man-command 'man
6772 "The Emacs command to be used to display a man page."
6774 :type '(choice (const man) (const woman)))
6776 (defun org-man-open (path)
6777 "Visit the manpage on PATH.
6778 PATH should be a topic that can be thrown at the man command."
6779 (funcall org-man-command path))
6781 (defun org-man-store-link ()
6782 "Store a link to a manpage."
6783 (when (memq major-mode '(Man-mode woman-mode))
6784 ;; This is a man page, we do make this link
6785 (let* ((page (org-man-get-page-name))
6786 (link (concat "man:" page))
6787 (description (format "Manpage for %s" page)))
6788 (org-store-link-props
6791 :description description))))
6793 (defun org-man-get-page-name ()
6794 "Extract the page name from the buffer name."
6795 ;; This works for both `Man-mode' and `woman-mode'.
6796 (if (string-match " \\(\\S-+\\)\\*" (buffer-name))
6797 (match-string 1 (buffer-name))
6798 (error "Cannot create link to this man page")))
6802 ;;; org-man.el ends here
6804 You would activate this new link type in `.emacs' with
6808 Lets go through the file and see what it does.
6809 1. It does `(require 'org)' to make sure that `org.el' has been
6812 2. The next line calls `org-add-link-type' to define a new link type
6813 with prefix `man'. The call also contains the name of a function
6814 that will be called to follow such a link.
6816 3. The next line adds a function to `org-store-link-functions', in
6817 order to allow the command `C-c l' to record a useful link in a
6818 buffer displaying a man page.
6820 The rest of the file defines the necessary variables and functions.
6821 First there is a customization variable that determines which emacs
6822 command should be used to display manpages. There are two options,
6823 `man' and `woman'. Then the function to follow a link is defined. It
6824 gets the link path as an argument - in this case the link path is just
6825 a topic for the manual command. The function calls the value of
6826 `org-man-command' to display the man page.
6828 Finally the function `org-man-store-link' is defined. When you try
6829 to store a link with `C-c l', also this function will be called to try
6830 to make a link. The function must first decide if it is supposed to
6831 create the link for this buffer type, we do this by checking the value
6832 of the variable `major-mode'. If not, the function must exit and
6833 retunr the value `nil'. If yes, the link is created by getting the
6834 manual tpoic from the buffer name and prefixing it with the string
6835 `man:'. Then it must call the command `org-store-link-props' and set
6836 the `:type' and `:link' properties. Optionally you can also set the
6837 `:description' property to provide a default for the link description
6838 when the link is later inserted into tan Org-mode buffer with `C-c C-l'.
6841 File: org, Node: Tables in arbitrary syntax, Next: Dynamic blocks, Prev: Adding hyperlink types, Up: Extensions and Hacking
6843 A.3 Tables in arbitrary syntax
6844 ==============================
6846 Since Orgtbl-mode can be used as a minor mode in arbitrary buffers, a
6847 frequent feature request has been to make it work with native tables in
6848 specific languages, for example LaTeX. However, this is extremely hard
6849 to do in a general way, would lead to a customization nightmare, and
6850 would take away much of the simplicity of the Orgtbl-mode table editor.
6852 This appendix describes a different approach. We keep the
6853 Orgtbl-mode table in its native format (the source table), and use a
6854 custom function to translate the table to the correct syntax, and to
6855 install it in the right location (the target table). This puts the
6856 burden of writing conversion functions on the user, but it allows for a
6857 very flexible system.
6861 * Radio tables:: Sending and receiving
6862 * A LaTeX example:: Step by step, almost a tutorial
6863 * Translator functions:: Copy and modify
6866 File: org, Node: Radio tables, Next: A LaTeX example, Prev: Tables in arbitrary syntax, Up: Tables in arbitrary syntax
6871 To define the location of the target table, you first need to create two
6872 lines that are comments in the current mode, but contain magic words for
6873 Orgtbl-mode to find. Orgtbl-mode will insert the translated table
6874 between these lines, replacing whatever was there before. For example:
6876 /* BEGIN RECEIVE ORGTBL table_name */
6877 /* END RECEIVE ORGTBL table_name */
6879 Just above the source table, we put a special line that tells
6880 Orgtbl-mode how to translate this table and where to install it. For
6882 #+ORGTBL: SEND table_name translation_function arguments....
6884 `table_name' is the reference name for the table that is also used in
6885 the receiver lines. `translation_function' is the Lisp function that
6886 does the translation. Furthermore, the line can contain a list of
6887 arguments (alternating key and value) at the end. The arguments will be
6888 passed as a property list to the translation function for
6889 interpretation. A few standard parameters are already recognized and
6890 acted upon before the translation function is called:
6893 Skip the first N lines of the table. Hlines do count!
6895 `:skipcols (n1 n2 ...)'
6896 List of columns that should be skipped. If the table has a column
6897 with calculation marks, that column is automatically discarded as
6898 well. Please note that the translator function sees the table
6899 _after_ the removal of these columns, the function never knows
6900 that there have been additional columns.
6902 The one problem remaining is how to keep the source table in the buffer
6903 without disturbing the normal workings of the file, for example during
6904 compilation of a C file or processing of a LaTeX file. There are a
6905 number of different solutions:
6907 * The table could be placed in a block comment if that is supported
6908 by the language. For example, in C-mode you could wrap the table
6909 between `/*' and `*/' lines.
6911 * Sometimes it is possible to put the table after some kind of END
6912 statement, for example `\bye' in TeX and `\end{document}' in LaTeX.
6914 * You can just comment the table line by line whenever you want to
6915 process the file, and uncomment it whenever you need to edit the
6916 table. This only sounds tedious - the command `M-x
6917 orgtbl-toggle-comment' does make this comment-toggling very easy,
6918 in particular if you bind it to a key.
6921 File: org, Node: A LaTeX example, Next: Translator functions, Prev: Radio tables, Up: Tables in arbitrary syntax
6923 A.3.2 A LaTeX example
6924 ---------------------
6926 The best way to wrap the source table in LaTeX is to use the `comment'
6927 environment provided by `comment.sty'. It has to be activated by
6928 placing `\usepackage{comment}' into the document header. Orgtbl-mode
6929 can insert a radio table skeleton(1) with the command `M-x
6930 orgtbl-insert-radio-table'. You will be prompted for a table name,
6931 lets say we use `salesfigures'. You will then get the following
6934 % BEGIN RECEIVE ORGTBL salesfigures
6935 % END RECEIVE ORGTBL salesfigures
6937 #+ORGTBL: SEND salesfigures orgtbl-to-latex
6941 The `#+ORGTBL: SEND' line tells orgtbl-mode to use the function
6942 `orgtbl-to-latex' to convert the table into LaTeX and to put it into
6943 the receiver location with name `salesfigures'. You may now fill in
6944 the table, feel free to use the spreadsheet features(2):
6946 % BEGIN RECEIVE ORGTBL salesfigures
6947 % END RECEIVE ORGTBL salesfigures
6949 #+ORGTBL: SEND salesfigures orgtbl-to-latex
6950 | Month | Days | Nr sold | per day |
6951 |-------+------+---------+---------|
6952 | Jan | 23 | 55 | 2.4 |
6953 | Feb | 21 | 16 | 0.8 |
6954 | March | 22 | 278 | 12.6 |
6955 #+TBLFM: $4=$3/$2;%.1f
6956 % $ (optional extra dollar to keep font-lock happy, see footnote)
6959 When you are done, press `C-c C-c' in the table to get the converted
6960 table inserted between the two marker lines.
6962 Now lets assume you want to make the table header by hand, because
6963 you want to control how columns are aligned etc. In this case we make
6964 sure that the table translator does skip the first 2 lines of the source
6965 table, and tell the command to work as a splice, i.e. to not produce
6966 header and footer commands of the target table:
6968 \begin{tabular}{lrrr}
6969 Month & \multicolumn{1}{c}{Days} & Nr.\ sold & per day\\
6970 % BEGIN RECEIVE ORGTBL salesfigures
6971 % END RECEIVE ORGTBL salesfigures
6975 #+ORGTBL: SEND salesfigures orgtbl-to-latex :splice t :skip 2
6976 | Month | Days | Nr sold | per day |
6977 |-------+------+---------+---------|
6978 | Jan | 23 | 55 | 2.4 |
6979 | Feb | 21 | 16 | 0.8 |
6980 | March | 22 | 278 | 12.6 |
6981 #+TBLFM: $4=$3/$2;%.1f
6984 The LaTeX translator function `orgtbl-to-latex' is already part of
6985 Orgtbl-mode. It uses a `tabular' environment to typeset the table and
6986 marks horizontal lines with `\hline'. Furthermore, it interprets the
6987 following parameters:
6990 When set to t, return only table body lines, don't wrap them into a
6991 tabular environment. Default is nil.
6994 A format to be used to wrap each field, should contain `%s' for the
6995 original field value. For example, to wrap each field value in
6996 dollars, you could use `:fmt "$%s$"'. This may also be a property
6997 list with column numbers and formats. for example `:fmt (2 "$%s$"
7001 Use this format to print numbers with exponentials. The format
7002 should have `%s' twice for inserting mantissa and exponent, for
7003 example `"%s\\times10^{%s}"'. The default is `"%s\\,(%s)"'. This
7004 may also be a property list with column numbers and formats, for
7005 example `:efmt (2 "$%s\\times10^{%s}$" 4 "$%s\\cdot10^{%s}$")'.
7006 After `efmt' has been applied to a value, `fmt' will also be
7009 ---------- Footnotes ----------
7011 (1) By default this works only for LaTeX, HTML, and TeXInfo.
7012 Configure the variable `orgtbl-radio-tables' to install templates for
7015 (2) If the `#+TBLFM' line contains an odd number of dollar
7016 characters, this may cause problems with font-lock in latex-mode. As
7017 shown in the example you can fix this by adding an extra line inside the
7018 `comment' environment that is used to balance the dollar expressions.
7019 If you are using AUCTeX with the font-latex library, a much better
7020 solution is to add the `comment' environment to the variable
7021 `LaTeX-verbatim-environments'.
7024 File: org, Node: Translator functions, Prev: A LaTeX example, Up: Tables in arbitrary syntax
7026 A.3.3 Translator functions
7027 --------------------------
7029 Orgtbl-mode has several translator functions built-in:
7030 `orgtbl-to-latex', `orgtbl-to-html', and `orgtbl-to-texinfo'. Except
7031 for `orgtbl-to-html'(1), these all use a generic translator,
7032 `orgtbl-to-generic'. For example, `orgtbl-to-latex' itself is a very
7033 short function that computes the column definitions for the `tabular'
7034 environment, defines a few field and line separators and then hands
7035 over to the generic translator. Here is the entire code:
7037 (defun orgtbl-to-latex (table params)
7038 "Convert the orgtbl-mode TABLE to LaTeX."
7039 (let* ((alignment (mapconcat (lambda (x) (if x "r" "l"))
7040 org-table-last-alignment ""))
7043 :tstart (concat "\\begin{tabular}{" alignment "}")
7044 :tend "\\end{tabular}"
7045 :lstart "" :lend " \\\\" :sep " & "
7046 :efmt "%s\\,(%s)" :hline "\\hline")))
7047 (orgtbl-to-generic table (org-combine-plists params2 params))))
7049 As you can see, the properties passed into the function (variable
7050 PARAMS) are combined with the ones newly defined in the function
7051 (variable PARAMS2). The ones passed into the function (i.e. the ones
7052 set by the `ORGTBL SEND' line) take precedence. So if you would like
7053 to use the LaTeX translator, but wanted the line endings to be
7054 `\\[2mm]' instead of the default `\\', you could just overrule the
7057 #+ORGTBL: SEND test orgtbl-to-latex :lend " \\\\[2mm]"
7059 For a new language, you can either write your own converter function
7060 in analogy with the LaTeX translator, or you can use the generic
7061 function directly. For example, if you have a language where a table
7062 is started with `!BTBL!', ended with `!ETBL!', and where table lines are
7063 started with `!BL!', ended with `!EL!' and where the field separator is
7064 a TAB, you could call the generic translator like this (on a single
7067 #+ORGTBL: SEND test orgtbl-to-generic :tstart "!BTBL!" :tend "!ETBL!"
7068 :lstart "!BL! " :lend " !EL!" :sep "\t"
7070 Please check the documentation string of the function
7071 `orgtbl-to-generic' for a full list of parameters understood by that
7072 function and remember that you can pass each of them into
7073 `orgtbl-to-latex', `orgtbl-to-texinfo', and any other function using
7074 the generic function.
7076 Of course you can also write a completely new function doing
7077 complicated things the generic translator cannot do. A translator
7078 function takes two arguments. The first argument is the table, a list
7079 of lines, each line either the symbol `hline' or a list of fields. The
7080 second argument is the property list containing all parameters
7081 specified in the `#+ORGTBL: SEND' line. The function must return a
7082 single string containing the formatted table. If you write a generally
7083 useful translator, please post it on `emacs-orgmode@gnu.org' so that
7084 others can benefit from your work.
7086 ---------- Footnotes ----------
7088 (1) The HTML translator uses the same code that produces tables
7092 File: org, Node: Dynamic blocks, Next: Special agenda views, Prev: Tables in arbitrary syntax, Up: Extensions and Hacking
7097 Org-mode documents can contain _dynamic blocks_. These are specially
7098 marked regions that are updated by some user-written function. A good
7099 example for such a block is the clock table inserted by the command
7100 `C-c C-x C-r' (*note Clocking work time::).
7102 Dynamic block are enclosed by a BEGIN-END structure that assigns a
7103 name to the block and can also specify parameters for the function
7104 producing the content of the block.
7106 #+BEGIN: myblock :parameter1 value1 :parameter2 value2 ...
7110 Dynamic blocks are updated with the following commands
7113 Update dynamic block at point.
7116 Update all dynamic blocks in the current file.
7118 Updating a dynamic block means to remove all the text between BEGIN
7119 and END, parse the BEGIN line for parameters and then call the specific
7120 writer function for this block to insert the new content. For a block
7121 with name `myblock', the writer function is `org-dblock-write:myblock'
7122 with as only parameter a property list with the parameters given in the
7123 begin line. Here is a trivial example of a block that keeps track of
7124 when the block update function was last run:
7126 #+BEGIN: block-update-time :format "on %m/%d/%Y at %H:%M"
7130 The corresponding block writer function could look like this:
7132 (defun org-dblock-write:block-update-time (params)
7133 (let ((fmt (or (plist-get params :format) "%d. %m. %Y")))
7134 (insert "Last block update at: "
7135 (format-time-string fmt (current-time)))))
7137 If you want to make sure that all dynamic blocks are always
7138 up-to-date, you could add the function `org-update-all-dblocks' to a
7139 hook, for example `before-save-hook'. `org-update-all-dblocks' is
7140 written in a way that is does nothing in buffers that are not in
7144 File: org, Node: Special agenda views, Next: Using the property API, Prev: Dynamic blocks, Up: Extensions and Hacking
7146 A.5 Special Agenda Views
7147 ========================
7149 Org-mode provides a special hook that can be used to narrow down the
7150 selection made by any of the agenda views. You may specify a function
7151 that is used at each match to verify if the match should indeed be part
7152 of the agenda view, and if not, how much should be skipped.
7154 Let's say you want to produce a list of projects that contain a
7155 WAITING tag anywhere in the project tree. Let's further assume that
7156 you have marked all tree headings that define a project with the todo
7157 keyword PROJECT. In this case you would run a todo search for the
7158 keyword PROJECT, but skip the match unless there is a WAITING tag
7159 anywhere in the subtree belonging to the project line.
7161 To achieve this, you must write a function that searches the subtree
7162 for the tag. If the tag is found, the function must return `nil' to
7163 indicate that this match should not be skipped. If there is no such
7164 tag, return the location of the end of the subtree, to indicate that
7165 search should continue from there.
7167 (defun my-skip-unless-waiting ()
7168 "Skip trees that are not waiting"
7169 (let ((subtree-end (save-excursion (org-end-of-subtree t))))
7170 (if (re-search-forward ":WAITING:" subtree-end t)
7171 nil ; tag found, do not skip
7172 subtree-end))) ; tag not found, continue after end of subtree
7174 Now you may use this function in an agenda custom command, for
7177 (org-add-agenda-custom-command
7178 '("b" todo "PROJECT"
7179 ((org-agenda-skip-function 'my-org-waiting-projects)
7180 (org-agenda-overriding-header "Projects waiting for something: "))))
7182 Note that this also binds `org-agenda-overriding-header' to get a
7183 meaningful header in the agenda view.
7185 You may also put a Lisp form into `org-agenda-skip-function'. In
7186 particular, you may use the functions `org-agenda-skip-entry-if' and
7187 `org-agenda-skip-subtree-if' in this form, for example:
7189 `'(org-agenda-skip-entry-if 'scheduled)'
7190 Skip current entry if it has been scheduled.
7192 `'(org-agenda-skip-entry-if 'notscheduled)'
7193 Skip current entry if it has not been scheduled.
7195 `'(org-agenda-skip-entry-if 'deadline)'
7196 Skip current entry if it has a deadline.
7198 `'(org-agenda-skip-entry-if 'scheduled 'deadline)'
7199 Skip current entry if it has a deadline, or if it is scheduled.
7201 `'(org-agenda-skip-entry 'regexp "regular expression")'
7202 Skip current entry if the regular expression matches in the entry.
7204 `'(org-agenda-skip-entry 'notregexp "regular expression")'
7205 Skip current entry unless the regular expression matches.
7207 `'(org-agenda-skip-subtree-if 'regexp "regular expression")'
7208 Same as above, but check and skip the entire subtree.
7210 Therefore we could also have written the search for WAITING projects
7211 like this, even without defining a special function:
7213 (org-add-agenda-custom-command
7214 '("b" todo "PROJECT"
7215 ((org-agenda-skip-function '(org-agenda-skip-subtree-if
7216 'regexp ":WAITING:"))
7217 (org-agenda-overriding-header "Projects waiting for something: "))))
7220 File: org, Node: Using the property API, Prev: Special agenda views, Up: Extensions and Hacking
7222 A.6 Using the property API
7223 ==========================
7225 Here is a description of the functions that can be used to work with
7228 -- Function: org-entry-properties &optional pom which
7229 Get all properties of the entry at point-or-marker POM. This
7230 includes the TODO keyword, the tags, time strings for deadline,
7231 scheduled, and clocking, and any additional properties defined in
7232 the entry. The return value is an alist, keys may occur multiple
7233 times if the property key was used several times. POM may also be
7234 nil, in which case the current entry is used. If WHICH is nil or
7235 `all', get all properties. If WHICH is `special' or `standard',
7236 only get that subclass.
7238 -- Function: org-entry-get pom property &optional inherit
7239 Get value of PROPERTY for entry at point-or-marker POM. If
7240 INHERIT is non-nil and the entry does not have the property, then
7241 also check higher levels of the hierarchy.
7243 -- Function: org-entry-delete pom property
7244 Delete the property PROPERTY from entry at point-or-marker POM.
7246 -- Function: org-entry-put pom property value
7247 Set PROPERTY to VALUE for entry at point-or-marker POM.
7249 -- Function: org-buffer-property-keys &optional include-specials
7250 Get all property keys in the current buffer.
7252 -- Function: org-insert-property-drawer
7253 Insert a property drawer at point.
7256 File: org, Node: History and Acknowledgments, Next: Index, Prev: Extensions and Hacking, Up: Top
7258 Appendix B History and Acknowledgments
7259 **************************************
7261 Org-mode was borne in 2003, out of frustration over the user interface
7262 of the Emacs outline-mode. I was trying to organize my notes and
7263 projects, and using Emacs seemed to be the natural way to go. However,
7264 having to remember eleven different commands with two or three keys per
7265 command, only to hide and unhide parts of the outline tree, that seemed
7266 entirely unacceptable to me. Also, when using outlines to take notes, I
7267 constantly want to restructure the tree, organizing it parallel to my
7268 thoughts and plans. _Visibility cycling_ and _structure editing_ were
7269 originally implemented in the package `outline-magic.el', but quickly
7270 moved to the more general `org.el'. As this environment became
7271 comfortable for project planning, the next step was adding _TODO
7272 entries_, basic _time stamps_, and _table support_. These areas
7273 highlight the two main goals that Org-mode still has today: To create a
7274 new, outline-based, plain text mode with innovative and intuitive
7275 editing features, and to incorporate project planning functionality
7276 directly into a notes file.
7278 Since the first release, literally thousands of emails to me or on
7279 `emacs-orgmode@gnu.org' have provided a constant stream of bug reports,
7280 feedback, new ideas, and sometimes patches and add-on code. Many
7281 thanks to everyone who has helped to improve this package. I am trying
7282 to keep here a list of the people who had significant influence in
7283 shaping one or more aspects of Org-mode. The list may not be complete,
7284 if I have forgotten someone, please accept my apologies and let me know.
7286 * Russel Adams came up with the idea for drawers.
7288 * Thomas Baumann contributed the code for links to the MH-E email
7291 * Alex Bochannek provided a patch for rounding time stamps.
7293 * Charles Cave's suggestion sparked the implementation of templates
7296 * Pavel Chalmoviansky influenced the agenda treatment of items with
7299 * Gregory Chernov patched support for lisp forms into table
7300 calculations and improved XEmacs compatibility, in particular by
7301 porting `nouline.el' to XEmacs.
7303 * Sacha Chua suggested to copy some linking code from Planner.
7305 * Eddward DeVilla proposed and tested checkbox statistics. He also
7306 came up with the idea of properties, and that there should be an
7309 * Kees Dullemond used to edit projects lists directly in HTML and so
7310 inspired some of the early development, including HTML export. He
7311 also asked for a way to narrow wide table columns.
7313 * Christian Egli converted the documentation into TeXInfo format,
7314 patched CSS formatting into the HTML exporter, and inspired the
7317 * David Emery provided a patch for custom CSS support in exported
7320 * Nic Ferrier contributed mailcap and XOXO support.
7322 * John Foerch figured out how to make incremental search show context
7323 around a match in a hidden outline tree.
7325 * Niels Giessen had the idea to automatically archive DONE trees.
7327 * Bastien Guerry wrote the LaTeX exporter and has been prolific with
7328 patches, ideas, and bug reports. to Org-mode.
7330 * Kai Grossjohann pointed out key-binding conflicts with other
7333 * Scott Jaderholm proposed footnotes, control over whitespace between
7334 folded entries, and column view for properties.
7336 * Shidai Liu ("Leo") asked for embedded LaTeX and tested it. He also
7337 provided frequent feedback and some patches.
7339 * Jason F. McBrayer suggested agenda export to CSV format.
7341 * Dmitri Minaev sent a patch to set priority limits on a per-file
7344 * Stefan Monnier provided a patch to keep the Emacs-Lisp compiler
7347 * Rick Moynihan proposed to allow multiple TODO sequences in a file.
7349 * Todd Neal provided patches for links to Info files and elisp forms.
7351 * Tim O'Callaghan suggested in-file links, search options for general
7352 file links, and TAGS.
7354 * Takeshi Okano translated the manual and David O'Toole's tutorial
7357 * Oliver Oppitz suggested multi-state TODO items.
7359 * Scott Otterson sparked the introduction of descriptive text for
7360 links, among other things.
7362 * Pete Phillips helped during the development of the TAGS feature,
7363 and provided frequent feedback.
7365 * T.V. Raman reported bugs and suggested improvements.
7367 * Matthias Rempe (Oelde) provided ideas, Windows support, and quality
7370 * Kevin Rogers contributed code to access VM files on remote hosts.
7372 * Frank Ruell solved the mystery of the `keymapp nil' bug, a
7373 conflict with `allout.el'.
7375 * Jason Riedy sent a patch to fix a bug with export of TODO keywords.
7377 * Philip Rooke created the Org-mode reference card and provided lots
7380 * Christian Schlauer proposed angular brackets around links, among
7383 * Linking to VM/BBDB/GNUS was inspired by Tom Shannon's
7384 `organizer-mode.el'.
7386 * Daniel Sinder came up with the idea of internal archiving by
7389 * Dale Smith proposed link abbreviations.
7391 * Adam Spiers asked for global linking commands and inspired the link
7392 extension system. support mairix.
7394 * David O'Toole wrote `org-publish.el' and drafted the manual
7395 chapter about publishing.
7397 * Ju"rgen Vollmer contributed code generating the table of contents
7400 * Chris Wallace provided a patch implementing the `QUOTE' keyword.
7402 * David Wainberg suggested archiving, and improvements to the linking
7405 * John Wiegley wrote `emacs-wiki.el' and `planner.el'. The
7406 development of Org-mode was fully independent, and both systems are
7407 really different beasts in their basic ideas and implementation
7408 details. I later looked at John's code, however, and learned from
7409 his implementation of (i) links where the link itself is hidden
7410 and only a description is shown, and (ii) popping up a calendar to
7411 select a date. John has also contributed a number of great ideas
7412 directly to Org-mode.
7414 * Carsten Wimmer suggested some changes and helped fix a bug in
7417 * Roland Winkler requested additional keybindings to make Org-mode
7420 * Piotr Zielinski wrote `org-mouse.el', proposed agenda blocks and
7421 contributed various ideas and code snippets.
7424 File: org, Node: Index, Next: Key Index, Prev: History and Acknowledgments, Up: Top
7432 * abbreviation, links: Link abbreviations. (line 6)
7433 * acknowledgments: History and Acknowledgments.
7435 * action, for publishing: Publishing action. (line 6)
7436 * activation: Activation. (line 6)
7437 * active region <1>: Structure editing. (line 68)
7438 * active region <2>: ASCII export. (line 9)
7439 * active region <3>: Built-in table editor.
7441 * active region: HTML Export commands.
7443 * agenda: Weekly/Daily agenda. (line 6)
7444 * agenda dispatcher: Agenda dispatcher. (line 6)
7445 * agenda files: Agenda files. (line 6)
7446 * agenda files, removing buffers: Agenda commands. (line 240)
7447 * agenda views: Agenda views. (line 6)
7448 * agenda views, custom: Custom agenda views. (line 6)
7449 * agenda views, exporting <1>: Agenda commands. (line 229)
7450 * agenda views, exporting: Exporting Agenda Views.
7452 * agenda views, user-defined: Special agenda views.
7454 * agenda, pipe: Extracting Agenda Information for other programs.
7456 * agenda, with block views: Block agenda. (line 6)
7457 * align, STARTUP keyword: In-buffer settings. (line 68)
7458 * allout.el: Conflicts. (line 6)
7459 * angular brackets, around links: External links. (line 43)
7460 * API, for properties <1>: Property API. (line 6)
7461 * API, for properties: Using the property API.
7463 * archive locations: Moving subtrees. (line 23)
7464 * archiving: Archiving. (line 6)
7465 * ASCII export: ASCII export. (line 6)
7466 * author: Feedback. (line 6)
7467 * author info, in export: Export options. (line 26)
7468 * autoload: Activation. (line 6)
7469 * backtrace of an error: Feedback. (line 27)
7470 * BBDB links: External links. (line 6)
7471 * block agenda: Block agenda. (line 6)
7472 * blorg.el: Extensions. (line 32)
7473 * bold text: Enhancing text. (line 15)
7474 * Boolean logic, for tag searches: Tag searches. (line 23)
7475 * bug reports: Feedback. (line 6)
7476 * bugs: Bugs. (line 6)
7477 * C-c C-c, overview: The very busy C-c C-c key.
7479 * calc package: The spreadsheet. (line 6)
7480 * calc.el: Cooperation. (line 6)
7481 * calculations, in tables <1>: The spreadsheet. (line 6)
7482 * calculations, in tables: Built-in table editor.
7484 * calendar commands, from agenda: Agenda commands. (line 192)
7485 * calendar integration: Weekly/Daily agenda. (line 24)
7486 * calendar, for selecting date: The date/time prompt.
7488 * category: Categories. (line 6)
7489 * CDLaTeX: CDLaTeX mode. (line 6)
7490 * cdlatex.el: Cooperation. (line 29)
7491 * checkbox statistics: Checkboxes. (line 23)
7492 * checkboxes: Checkboxes. (line 6)
7493 * children, subtree visibility state: Visibility cycling. (line 10)
7494 * clean outline view: Clean view. (line 6)
7495 * column formula: Column formulas. (line 6)
7496 * column view, for properties: Defining columns. (line 6)
7497 * commands, in agenda buffer: Agenda commands. (line 6)
7498 * comment lines: Comment lines. (line 6)
7499 * completion, of dictionary words: Completion. (line 6)
7500 * completion, of file names: Handling links. (line 43)
7501 * completion, of link abbreviations: Completion. (line 6)
7502 * completion, of links: Handling links. (line 25)
7503 * completion, of option keywords <1>: Export options. (line 6)
7504 * completion, of option keywords <2>: Per file keywords. (line 23)
7505 * completion, of option keywords: Completion. (line 6)
7506 * completion, of property keys: Completion. (line 6)
7507 * completion, of tags <1>: Setting tags. (line 11)
7508 * completion, of tags: Completion. (line 6)
7509 * completion, of TeX symbols: Completion. (line 6)
7510 * completion, of TODO keywords <1>: Workflow states. (line 15)
7511 * completion, of TODO keywords: Completion. (line 6)
7512 * constants, in calculations: References. (line 82)
7513 * constants.el: Cooperation. (line 14)
7514 * constcgs, STARTUP keyword: In-buffer settings. (line 93)
7515 * constSI, STARTUP keyword: In-buffer settings. (line 93)
7516 * content, STARTUP keyword: In-buffer settings. (line 61)
7517 * contents, global visibility state: Visibility cycling. (line 22)
7518 * copying, of subtrees: Structure editing. (line 6)
7519 * creating timestamps: Creating timestamps. (line 6)
7520 * CUA.el: Conflicts. (line 15)
7521 * custom agenda views: Custom agenda views. (line 6)
7522 * custom date/time format: Custom time format. (line 6)
7523 * custom search strings: Custom searches. (line 6)
7524 * customization: Customization. (line 6)
7525 * customtime, STARTUP keyword: In-buffer settings. (line 90)
7526 * cutting, of subtrees: Structure editing. (line 6)
7527 * cycling, of TODO states: TODO basics. (line 13)
7528 * cycling, visibility: Visibility cycling. (line 6)
7529 * daily agenda: Weekly/Daily agenda. (line 6)
7530 * date format, custom: Custom time format. (line 6)
7531 * date range: Time stamps. (line 40)
7532 * date stamps <1>: Time stamps. (line 6)
7533 * date stamps: Timestamps. (line 6)
7534 * date, reading in minibuffer: The date/time prompt.
7536 * DEADLINE keyword: Deadlines and scheduling.
7538 * deadlines: Time stamps. (line 6)
7539 * debugging, of table formulas: Editing and debugging formulas.
7541 * demotion, of subtrees: Structure editing. (line 6)
7542 * diary entries, creating from agenda: Agenda commands. (line 197)
7543 * diary integration: Weekly/Daily agenda. (line 24)
7544 * dictionary word completion: Completion. (line 6)
7545 * directories, for publishing: Sources and destinations.
7547 * dispatching agenda commands: Agenda dispatcher. (line 6)
7548 * display changing, in agenda: Agenda commands. (line 65)
7549 * document structure: Document structure. (line 6)
7550 * DONE, final TODO keyword: Per file keywords. (line 26)
7551 * drawer, for properties: Property syntax. (line 6)
7552 * drawers: Drawers. (line 6)
7553 * dynamic blocks: Dynamic blocks. (line 6)
7554 * editing tables: Tables. (line 6)
7555 * editing, of table formulas: Editing and debugging formulas.
7557 * elisp links: External links. (line 6)
7558 * emphasized text: Export options. (line 26)
7559 * enhancing text: Enhancing text. (line 6)
7560 * evaluate time range: Creating timestamps. (line 48)
7561 * even, STARTUP keyword: In-buffer settings. (line 83)
7562 * exporting: Exporting. (line 6)
7563 * exporting agenda views <1>: Exporting Agenda Views.
7565 * exporting agenda views: Agenda commands. (line 229)
7566 * exporting, not: Comment lines. (line 6)
7567 * extended TODO keywords: TODO extensions. (line 6)
7568 * extension, third-party: Extensions. (line 6)
7569 * external archiving: Moving subtrees. (line 6)
7570 * external links: External links. (line 6)
7571 * external links, in HTML export: Links. (line 6)
7572 * faces, for TODO keywords: Faces for TODO keywords.
7574 * FAQ: Summary. (line 56)
7575 * feedback: Feedback. (line 6)
7576 * field formula: Field formulas. (line 6)
7577 * field references: References. (line 15)
7578 * file links: External links. (line 6)
7579 * file links, searching: Search options. (line 6)
7580 * file name completion: Handling links. (line 43)
7581 * files for agenda: Agenda files. (line 6)
7582 * files, adding to agenda list: Agenda files. (line 12)
7583 * files, selecting for publishing: Selecting files. (line 6)
7584 * fixed width: Enhancing text. (line 28)
7585 * fixed-width sections: Export options. (line 26)
7586 * folded, subtree visibility state: Visibility cycling. (line 10)
7587 * folding, sparse trees: Sparse trees. (line 6)
7588 * following links: Handling links. (line 58)
7589 * footnote.el <1>: Conflicts. (line 35)
7590 * footnote.el <2>: Cooperation. (line 56)
7591 * footnote.el: Footnotes. (line 6)
7592 * footnotes <1>: Export options. (line 26)
7593 * footnotes: Footnotes. (line 6)
7594 * format specifier: Formula syntax for Calc.
7596 * format, of links: Link format. (line 6)
7597 * formula debugging: Editing and debugging formulas.
7599 * formula editing: Editing and debugging formulas.
7601 * formula syntax, Calc: Formula syntax for Calc.
7603 * formula, for individual table field: Field formulas. (line 6)
7604 * formula, for table column: Column formulas. (line 6)
7605 * formula, in tables: Built-in table editor.
7607 * global cycling: Visibility cycling. (line 22)
7608 * global keybindings: Activation. (line 6)
7609 * global TODO list: Global TODO list. (line 6)
7610 * global visibility states: Visibility cycling. (line 22)
7611 * GNUS links: External links. (line 6)
7612 * grouping columns in tables: Column groups. (line 6)
7613 * hand-formatted lists: Enhancing text. (line 11)
7614 * headline levels: Export options. (line 26)
7615 * headline levels, for exporting <1>: HTML Export commands.
7617 * headline levels, for exporting <2>: LaTeX export commands.
7619 * headline levels, for exporting: ASCII export. (line 21)
7620 * headline navigation: Motion. (line 6)
7621 * headline tagging: Tags. (line 6)
7622 * headline, promotion and demotion: Structure editing. (line 6)
7623 * headlines: Headlines. (line 6)
7624 * hide text: Visibility cycling. (line 6)
7625 * hidestars, STARTUP keyword: In-buffer settings. (line 83)
7626 * hiding leading stars: Clean view. (line 6)
7627 * history: History and Acknowledgments.
7629 * horizontal rules, in exported files: Enhancing text. (line 18)
7630 * HTML export: HTML export. (line 6)
7631 * HTML, and orgtbl-mode: Translator functions.
7633 * hyperlinks: Hyperlinks. (line 6)
7634 * hyperlinks, adding new types: Adding hyperlink types.
7636 * iCalendar export: iCalendar export. (line 6)
7637 * images, inline in HTML: Images. (line 6)
7638 * in-buffer settings: In-buffer settings. (line 6)
7639 * inactive timestamp: Time stamps. (line 49)
7640 * index, of published pages: Project page index. (line 6)
7641 * Info links: External links. (line 6)
7642 * inheritance, of tags: Tag inheritance. (line 6)
7643 * inlining images in HTML: Images. (line 6)
7644 * inserting links: Handling links. (line 25)
7645 * installation: Installation. (line 6)
7646 * internal archiving: ARCHIVE tag. (line 6)
7647 * internal links: Internal links. (line 6)
7648 * internal links, in HTML export: Links. (line 6)
7649 * introduction: Introduction. (line 6)
7650 * italic text: Enhancing text. (line 15)
7651 * jumping, to headlines: Motion. (line 6)
7652 * keybindings, global: Activation. (line 6)
7653 * keyword options: Per file keywords. (line 6)
7654 * LaTeX export: LaTeX export. (line 6)
7655 * LaTeX fragments <1>: Export options. (line 26)
7656 * LaTeX fragments: LaTeX fragments. (line 6)
7657 * LaTeX fragments, export: Enhancing text. (line 21)
7658 * LaTeX fragments, preview: Processing LaTeX fragments.
7660 * LaTeX interpretation: Embedded LaTeX. (line 6)
7661 * LaTeX, and orgtbl-mode: A LaTeX example. (line 6)
7662 * level, require for tags match: Tag searches. (line 68)
7663 * linebreak preservation: Export options. (line 26)
7664 * linebreak, forced: Enhancing text. (line 35)
7665 * link abbreviations: Link abbreviations. (line 6)
7666 * link abbreviations, completion of: Completion. (line 6)
7667 * link completion: Handling links. (line 25)
7668 * link format: Link format. (line 6)
7669 * links, external: External links. (line 6)
7670 * links, finding next/previous: Handling links. (line 91)
7671 * links, handling: Handling links. (line 6)
7672 * links, in HTML export: Links. (line 6)
7673 * links, internal: Internal links. (line 6)
7674 * links, publishing: Publishing links. (line 6)
7675 * links, radio targets: Radio targets. (line 6)
7676 * links, returning to: Handling links. (line 85)
7677 * Lisp forms, as table formulas: Formula syntax for Lisp.
7679 * lists, hand-formatted: Enhancing text. (line 11)
7680 * lists, ordered: Plain lists. (line 6)
7681 * lists, plain: Plain lists. (line 6)
7682 * logdone, STARTUP keyword: In-buffer settings. (line 72)
7683 * logging, of progress: Progress logging. (line 6)
7684 * lognoteclock-out, STARTUP keyword: In-buffer settings. (line 72)
7685 * lognotedone, STARTUP keyword: In-buffer settings. (line 72)
7686 * lognotestate, STARTUP keyword: In-buffer settings. (line 72)
7687 * logrepeat, STARTUP keyword: In-buffer settings. (line 72)
7688 * maintainer: Feedback. (line 6)
7689 * mark ring: Handling links. (line 81)
7690 * marking characters, tables: Advanced features. (line 40)
7691 * matching, of properties: Matching tags and properties.
7693 * matching, of tags: Matching tags and properties.
7695 * matching, tags: Tags. (line 6)
7696 * math symbols: Math symbols. (line 6)
7697 * MH-E links: External links. (line 6)
7698 * minor mode for structure editing: orgstruct-mode. (line 6)
7699 * minor mode for tables: orgtbl-mode. (line 6)
7700 * mode, for calc: Formula syntax for Calc.
7702 * motion commands in agenda: Agenda commands. (line 19)
7703 * motion, between headlines: Motion. (line 6)
7704 * name, of column or field: References. (line 82)
7705 * named references: References. (line 82)
7706 * names as TODO keywords: TODO types. (line 6)
7707 * narrow columns in tables: Narrow columns. (line 6)
7708 * noalign, STARTUP keyword: In-buffer settings. (line 68)
7709 * nologging, STARTUP keyword: In-buffer settings. (line 72)
7710 * nologrepeat, STARTUP keyword: In-buffer settings. (line 72)
7711 * occur, command: Sparse trees. (line 6)
7712 * odd, STARTUP keyword: In-buffer settings. (line 83)
7713 * option keyword completion: Completion. (line 6)
7714 * options, for custom agenda views: Setting Options. (line 6)
7715 * options, for customization: Customization. (line 6)
7716 * options, for export: Export options. (line 6)
7717 * options, for publishing: Publishing options. (line 6)
7718 * ordered lists: Plain lists. (line 6)
7719 * org-agenda, command: Weekly/Daily agenda. (line 9)
7720 * org-blog.el: Extensions. (line 28)
7721 * org-mode, turning on: Activation. (line 22)
7722 * org-mouse.el: Extensions. (line 16)
7723 * org-publish-project-alist: Project alist. (line 6)
7724 * org-publish.el: Extensions. (line 8)
7725 * org2rem.el: Extensions. (line 36)
7726 * orgstruct-mode: orgstruct-mode. (line 6)
7727 * orgtbl-mode <1>: Tables in arbitrary syntax.
7729 * orgtbl-mode: orgtbl-mode. (line 6)
7730 * outline tree: Headlines. (line 6)
7731 * outline-mode: Outlines. (line 6)
7732 * outlines: Outlines. (line 6)
7733 * overview, global visibility state: Visibility cycling. (line 22)
7734 * overview, STARTUP keyword: In-buffer settings. (line 61)
7735 * packages, interaction with other: Interaction. (line 6)
7736 * pasting, of subtrees: Structure editing. (line 6)
7737 * per file keywords: Per file keywords. (line 6)
7738 * plain lists: Plain lists. (line 6)
7739 * plain text external links: External links. (line 43)
7740 * presentation, of agenda items: Presentation and sorting.
7742 * printing sparse trees: Sparse trees. (line 41)
7743 * priorities: Priorities. (line 6)
7744 * priorities, of agenda items: Sorting of agenda items.
7746 * progress logging: Progress logging. (line 6)
7747 * projects, for publishing: Project alist. (line 6)
7748 * promotion, of subtrees: Structure editing. (line 6)
7749 * properties: Properties and columns.
7751 * properties, API <1>: Using the property API.
7753 * properties, API: Property API. (line 6)
7754 * properties, column view: Defining columns. (line 6)
7755 * properties, searching: Property searches. (line 6)
7756 * properties, special: Special properties. (line 6)
7757 * property syntax: Property syntax. (line 6)
7758 * publishing: Publishing. (line 6)
7759 * quoted HTML tags: Export options. (line 26)
7760 * radio tables: Radio tables. (line 6)
7761 * radio targets: Radio targets. (line 6)
7762 * range references: References. (line 60)
7763 * ranges, time: Time stamps. (line 6)
7764 * recomputing table fields: Updating the table. (line 6)
7765 * references: References. (line 6)
7766 * references, named: References. (line 82)
7767 * references, to fields: References. (line 15)
7768 * references, to ranges: References. (line 60)
7769 * region, active <1>: Built-in table editor.
7771 * region, active <2>: ASCII export. (line 9)
7772 * region, active <3>: HTML Export commands.
7774 * region, active: Structure editing. (line 68)
7775 * regular expressions, with tags search: Tag searches. (line 63)
7776 * remember.el <1>: Remember. (line 6)
7777 * remember.el: Cooperation. (line 33)
7778 * remote editing, from agenda: Agenda commands. (line 106)
7779 * remote editing, undo: Agenda commands. (line 107)
7780 * richer text: Enhancing text. (line 6)
7781 * RMAIL links: External links. (line 6)
7782 * SCHEDULED keyword: Deadlines and scheduling.
7784 * scheduling: Time stamps. (line 6)
7785 * Scripts, for agenda processing: Extracting Agenda Information for other programs.
7787 * search option in file links: Search options. (line 6)
7788 * search strings, custom: Custom searches. (line 6)
7789 * searching for tags: Tag searches. (line 6)
7790 * section-numbers: Export options. (line 26)
7791 * setting tags: Setting tags. (line 6)
7792 * SHELL links: External links. (line 6)
7793 * show all, command: Visibility cycling. (line 33)
7794 * show all, global visibility state: Visibility cycling. (line 22)
7795 * show hidden text: Visibility cycling. (line 6)
7796 * showall, STARTUP keyword: In-buffer settings. (line 61)
7797 * showstars, STARTUP keyword: In-buffer settings. (line 83)
7798 * sorting, of agenda items: Sorting of agenda items.
7800 * sparse tree, for deadlines: Inserting deadline/schedule.
7802 * sparse tree, for TODO: TODO basics. (line 38)
7803 * sparse tree, tag based: Tags. (line 6)
7804 * sparse trees: Sparse trees. (line 6)
7805 * special keywords: In-buffer settings. (line 6)
7806 * spreadsheet capabilities: The spreadsheet. (line 6)
7807 * statistics, for checkboxes: Checkboxes. (line 23)
7808 * storing links: Handling links. (line 9)
7809 * structure editing: Structure editing. (line 6)
7810 * structure of document: Document structure. (line 6)
7811 * sublevels, inclusion into tags match: Tag inheritance. (line 6)
7812 * sublevels, inclusion into todo list: Global TODO list. (line 34)
7813 * subscript: Subscripts and Superscripts.
7815 * subtree cycling: Visibility cycling. (line 10)
7816 * subtree visibility states: Visibility cycling. (line 10)
7817 * subtree, cut and paste: Structure editing. (line 6)
7818 * subtree, subtree visibility state: Visibility cycling. (line 10)
7819 * subtrees, cut and paste: Structure editing. (line 6)
7820 * summary: Summary. (line 6)
7821 * superscript: Subscripts and Superscripts.
7823 * syntax, of formulas: Formula syntax for Calc.
7825 * table editor, built-in: Built-in table editor.
7827 * table editor, table.el: Cooperation. (line 37)
7828 * table of contents: Export options. (line 26)
7829 * table.el: Cooperation. (line 37)
7830 * tables <1>: Export options. (line 26)
7831 * tables: Tables. (line 6)
7832 * tables, export: Enhancing text. (line 24)
7833 * tables, in other modes: Tables in arbitrary syntax.
7835 * tag completion: Completion. (line 6)
7836 * tag searches: Tag searches. (line 6)
7837 * tags: Tags. (line 6)
7838 * tags view: Matching tags and properties.
7840 * tags, setting: Setting tags. (line 6)
7841 * targets, for links: Internal links. (line 6)
7842 * targets, radio: Radio targets. (line 6)
7843 * tasks, breaking down: Breaking down tasks. (line 6)
7844 * templates, for remember: Remember templates. (line 6)
7845 * TeX interpretation: Embedded LaTeX. (line 6)
7846 * TeX macros <1>: Export options. (line 26)
7847 * TeX macros: Math symbols. (line 6)
7848 * TeX macros, export: Enhancing text. (line 21)
7849 * TeX symbol completion: Completion. (line 6)
7850 * TeX-like syntax for sub- and superscripts: Export options. (line 26)
7851 * thanks: History and Acknowledgments.
7853 * time format, custom: Custom time format. (line 6)
7854 * time grid: Time-of-day specifications.
7856 * time info, in export: Export options. (line 26)
7857 * time stamps <1>: Timestamps. (line 6)
7858 * time stamps: Time stamps. (line 6)
7859 * time, reading in minibuffer: The date/time prompt.
7861 * time-of-day specification: Time-of-day specifications.
7863 * time-sorted view: Timeline. (line 6)
7864 * timeline, single file: Timeline. (line 6)
7865 * timerange: Time stamps. (line 40)
7866 * timestamp: Time stamps. (line 14)
7867 * timestamp, inactive: Time stamps. (line 49)
7868 * timestamp, with repeater interval: Time stamps. (line 24)
7869 * timestamps, creating: Creating timestamps. (line 6)
7870 * TODO items: TODO items. (line 6)
7871 * TODO keyword matching: Global TODO list. (line 17)
7872 * TODO keyword matching, with tags search: Tag searches. (line 40)
7873 * todo keyword sets: Multiple sets in one file.
7875 * TODO keywords completion: Completion. (line 6)
7876 * TODO list, global: Global TODO list. (line 6)
7877 * TODO types: TODO types. (line 6)
7878 * TODO workflow: Workflow states. (line 6)
7879 * transient-mark-mode <1>: Structure editing. (line 68)
7880 * transient-mark-mode <2>: Built-in table editor.
7882 * transient-mark-mode <3>: HTML Export commands.
7884 * transient-mark-mode: ASCII export. (line 9)
7885 * translator function: Translator functions.
7887 * trees, sparse: Sparse trees. (line 6)
7888 * trees, visibility: Visibility cycling. (line 6)
7889 * tty keybindings: TTY keys. (line 6)
7890 * types as TODO keywords: TODO types. (line 6)
7891 * underlined text: Enhancing text. (line 15)
7892 * undoing remote-editing events: Agenda commands. (line 107)
7893 * updating, table: Updating the table. (line 6)
7894 * URL links: External links. (line 6)
7895 * USENET links: External links. (line 6)
7896 * variables, for customization: Customization. (line 6)
7897 * vectors, in table calculations: Formula syntax for Calc.
7899 * visibility cycling: Visibility cycling. (line 6)
7900 * visibility cycling, drawers: Drawers. (line 6)
7901 * visible text, printing: Sparse trees. (line 41)
7902 * VM links: External links. (line 6)
7903 * WANDERLUST links: External links. (line 6)
7904 * weekly agenda: Weekly/Daily agenda. (line 6)
7905 * windmove.el: Conflicts. (line 32)
7906 * workflow states as TODO keywords: Workflow states. (line 6)
7907 * XEmacs: Installation. (line 6)
7908 * XOXO export: XOXO export. (line 6)
7911 File: org, Node: Key Index, Prev: Index, Up: Top
7919 * $: Agenda commands. (line 121)
7920 * ': CDLaTeX mode. (line 43)
7921 * +: Agenda commands. (line 144)
7922 * ,: Agenda commands. (line 136)
7923 * -: Agenda commands. (line 150)
7924 * .: Agenda commands. (line 98)
7925 * :: Agenda commands. (line 129)
7926 * < <1>: Using column view. (line 54)
7927 * <: The date/time prompt.
7929 * <left>: Agenda commands. (line 95)
7930 * <RET> <1>: Built-in table editor.
7932 * <RET> <2>: The date/time prompt.
7934 * <RET> <3>: Agenda commands. (line 39)
7935 * <RET>: Setting tags. (line 76)
7936 * <right>: Agenda commands. (line 90)
7937 * <SPC> <1>: Setting tags. (line 73)
7938 * <SPC>: Agenda commands. (line 28)
7939 * <TAB> <1>: Built-in table editor.
7941 * <TAB> <2>: Agenda commands. (line 33)
7942 * <TAB> <3>: Visibility cycling. (line 10)
7943 * <TAB> <4>: Plain lists. (line 41)
7944 * <TAB> <5>: Setting tags. (line 68)
7945 * <TAB> <6>: CDLaTeX mode. (line 23)
7946 * <TAB>: Editing and debugging formulas.
7948 * > <1>: The date/time prompt.
7950 * > <2>: Using column view. (line 54)
7951 * >: Agenda commands. (line 172)
7952 * ^: CDLaTeX mode. (line 33)
7953 * _: CDLaTeX mode. (line 33)
7954 * `: CDLaTeX mode. (line 39)
7955 * a <1>: Using column view. (line 43)
7956 * a: Agenda commands. (line 133)
7957 * b: Agenda commands. (line 49)
7958 * c: Agenda commands. (line 192)
7959 * C: Agenda commands. (line 212)
7960 * C-#: Advanced features. (line 9)
7961 * C-': Agenda files. (line 18)
7962 * C-,: Agenda files. (line 18)
7963 * C-<RET>: Structure editing. (line 18)
7964 * C-_: Agenda commands. (line 107)
7965 * C-c ! <1>: Creating timestamps. (line 19)
7966 * C-c !: Footnotes. (line 14)
7967 * C-c #: Checkboxes. (line 57)
7968 * C-c %: Handling links. (line 81)
7969 * C-c &: Handling links. (line 85)
7970 * C-c ': Editing and debugging formulas.
7972 * C-c *: Updating the table. (line 13)
7973 * C-c +: Built-in table editor.
7975 * C-c ,: Priorities. (line 18)
7976 * C-c - <1>: Built-in table editor.
7978 * C-c -: Plain lists. (line 88)
7979 * C-c .: Creating timestamps. (line 10)
7980 * C-c /: Sparse trees. (line 15)
7981 * C-c :: Enhancing text. (line 32)
7982 * C-c ;: Comment lines. (line 10)
7983 * C-c <: Creating timestamps. (line 23)
7984 * C-c <TAB>: Built-in table editor.
7986 * C-c = <1>: Editing and debugging formulas.
7988 * C-c =: Column formulas. (line 26)
7989 * C-c >: Creating timestamps. (line 27)
7990 * C-c ?: Editing and debugging formulas.
7992 * C-c [: Agenda files. (line 12)
7993 * C-c \: Tag searches. (line 9)
7994 * C-c ]: Agenda files. (line 15)
7995 * C-c ^ <1>: Structure editing. (line 56)
7996 * C-c ^: Built-in table editor.
7998 * C-c `: Built-in table editor.
8000 * C-c a !: Stuck projects. (line 14)
8001 * C-c a #: Stuck projects. (line 13)
8002 * C-c a a: Weekly/Daily agenda. (line 9)
8003 * C-c a C: Storing searches. (line 9)
8004 * C-c a e: Exporting Agenda Views.
8006 * C-c a L: Timeline. (line 10)
8007 * C-c a M: Tag searches. (line 16)
8008 * C-c a m <1>: Tag searches. (line 12)
8009 * C-c a m: Matching tags and properties.
8011 * C-c a M: Matching tags and properties.
8013 * C-c a T: Global TODO list. (line 14)
8014 * C-c a t <1>: TODO basics. (line 48)
8015 * C-c a t: Global TODO list. (line 9)
8016 * C-c C-a: Visibility cycling. (line 33)
8017 * C-c C-b: Motion. (line 15)
8018 * C-c C-c <1>: TODO basics. (line 30)
8019 * C-c C-c <2>: Cooperation. (line 37)
8020 * C-c C-c <3>: The very busy C-c C-c key.
8022 * C-c C-c <4>: Processing LaTeX fragments.
8024 * C-c C-c <5>: Clocking work time. (line 79)
8025 * C-c C-c <6>: Property syntax. (line 54)
8026 * C-c C-c <7>: Setting tags. (line 10)
8027 * C-c C-c <8>: Checkboxes. (line 37)
8028 * C-c C-c <9>: Editing and debugging formulas.
8030 * C-c C-c <10>: Built-in table editor.
8032 * C-c C-c: Plain lists. (line 81)
8033 * C-c C-d <1>: Inserting deadline/schedule.
8035 * C-c C-d: Agenda commands. (line 157)
8036 * C-c C-e: Exporting. (line 20)
8037 * C-c C-e a: ASCII export. (line 9)
8038 * C-c C-e b: HTML Export commands.
8040 * C-c C-e c: iCalendar export. (line 21)
8041 * C-c C-e h: HTML Export commands.
8043 * C-c C-e H: HTML Export commands.
8045 * C-c C-e I: iCalendar export. (line 16)
8046 * C-c C-e i: iCalendar export. (line 14)
8047 * C-c C-e l: LaTeX export commands.
8049 * C-c C-e L: LaTeX export commands.
8051 * C-c C-e R: HTML Export commands.
8053 * C-c C-e t: Export options. (line 13)
8054 * C-c C-e v <1>: XOXO export. (line 11)
8055 * C-c C-e v: Sparse trees. (line 41)
8056 * C-c C-e v a: ASCII export. (line 16)
8057 * C-c C-e v b: HTML Export commands.
8059 * C-c C-e v h: HTML Export commands.
8061 * C-c C-e v H: HTML Export commands.
8063 * C-c C-e v l: LaTeX export commands.
8065 * C-c C-e v L: LaTeX export commands.
8067 * C-c C-e v R: HTML Export commands.
8069 * C-c C-e x: XOXO export. (line 10)
8070 * C-c C-f: Motion. (line 12)
8071 * C-c C-j: Motion. (line 21)
8072 * C-c C-l: Handling links. (line 25)
8073 * C-c C-n: Motion. (line 8)
8074 * C-c C-o <1>: Handling links. (line 58)
8075 * C-c C-o: Creating timestamps. (line 31)
8076 * C-c C-p: Motion. (line 9)
8077 * C-c C-q <1>: Editing and debugging formulas.
8079 * C-c C-q: Built-in table editor.
8081 * C-c C-r <1>: Editing and debugging formulas.
8083 * C-c C-r: Visibility cycling. (line 34)
8084 * C-c C-s <1>: Agenda commands. (line 154)
8085 * C-c C-s: Inserting deadline/schedule.
8087 * C-c C-t <1>: Clocking work time. (line 27)
8088 * C-c C-t: TODO basics. (line 13)
8089 * C-c C-u: Motion. (line 18)
8090 * C-c C-v: TODO basics. (line 38)
8091 * C-c C-w: Inserting deadline/schedule.
8093 * C-c C-x /: Agenda files. (line 22)
8094 * C-c C-x b: Visibility cycling. (line 41)
8095 * C-c C-x C-a: ARCHIVE tag. (line 28)
8096 * C-c C-x C-b: Checkboxes. (line 39)
8097 * C-c C-x C-c <1>: Agenda commands. (line 219)
8098 * C-c C-x C-c: Using column view. (line 9)
8099 * C-c C-x C-d: Clocking work time. (line 35)
8100 * C-c C-x C-i: Clocking work time. (line 12)
8101 * C-c C-x C-k: Structure editing. (line 43)
8102 * C-c C-x C-l: Processing LaTeX fragments.
8104 * C-c C-x C-n: Handling links. (line 91)
8105 * C-c C-x C-o: Clocking work time. (line 14)
8106 * C-c C-x C-p: Handling links. (line 91)
8107 * C-c C-x C-r: Clocking work time. (line 43)
8108 * C-c C-x C-s: Moving subtrees. (line 10)
8109 * C-c C-x C-t: Custom time format. (line 12)
8110 * C-c C-x C-u <1>: Dynamic blocks. (line 21)
8111 * C-c C-x C-u: Clocking work time. (line 81)
8112 * C-c C-x C-w <1>: Built-in table editor.
8114 * C-c C-x C-w: Structure editing. (line 43)
8115 * C-c C-x C-x: Clocking work time. (line 31)
8116 * C-c C-x C-y <1>: Built-in table editor.
8118 * C-c C-x C-y: Structure editing. (line 50)
8119 * C-c C-x M-w <1>: Built-in table editor.
8121 * C-c C-x M-w: Structure editing. (line 47)
8122 * C-c C-y <1>: Clocking work time. (line 22)
8123 * C-c C-y: Creating timestamps. (line 48)
8124 * C-c l: Handling links. (line 9)
8125 * C-c { <1>: Editing and debugging formulas.
8127 * C-c {: CDLaTeX mode. (line 21)
8128 * C-c |: Built-in table editor.
8130 * C-c }: Editing and debugging formulas.
8132 * C-c ~: Cooperation. (line 48)
8133 * C-k: Agenda commands. (line 115)
8134 * C-S-<left>: Multiple sets in one file.
8136 * C-S-<right>: Multiple sets in one file.
8138 * C-TAB: ARCHIVE tag. (line 38)
8139 * C-u C-c *: Updating the table. (line 16)
8140 * C-u C-c .: Creating timestamps. (line 14)
8141 * C-u C-c = <1>: Field formulas. (line 24)
8142 * C-u C-c =: Editing and debugging formulas.
8144 * C-u C-c C-c: Updating the table. (line 19)
8145 * C-u C-c C-l: Handling links. (line 43)
8146 * C-u C-c C-t: TODO basics. (line 22)
8147 * C-u C-c C-x C-a: ARCHIVE tag. (line 31)
8148 * C-u C-c C-x C-s: Moving subtrees. (line 14)
8149 * C-u C-c C-x C-u <1>: Clocking work time. (line 83)
8150 * C-u C-c C-x C-u: Dynamic blocks. (line 22)
8151 * C-u C-u C-c *: Updating the table. (line 22)
8152 * C-u C-u C-c =: Editing and debugging formulas.
8154 * C-u C-u C-c C-c: Updating the table. (line 22)
8155 * C-x C-s: Editing and debugging formulas.
8157 * C-x C-w <1>: Exporting Agenda Views.
8159 * C-x C-w: Agenda commands. (line 228)
8160 * D: Agenda commands. (line 72)
8161 * d: Agenda commands. (line 66)
8162 * e: Using column view. (line 33)
8163 * f: Agenda commands. (line 42)
8164 * g: Agenda commands. (line 76)
8165 * H: Agenda commands. (line 216)
8166 * I: Agenda commands. (line 177)
8167 * i: Agenda commands. (line 197)
8168 * L: Agenda commands. (line 30)
8169 * l: Agenda commands. (line 55)
8170 * m: Agenda commands. (line 66)
8171 * M: Agenda commands. (line 203)
8172 * M-<down> <1>: Editing and debugging formulas.
8174 * M-<down>: Built-in table editor.
8176 * M-<left> <1>: Structure editing. (line 25)
8177 * M-<left>: Built-in table editor.
8179 * M-<RET> <1>: Structure editing. (line 6)
8180 * M-<RET>: Plain lists. (line 49)
8181 * M-<right> <1>: Built-in table editor.
8183 * M-<right>: Structure editing. (line 28)
8184 * M-<TAB> <1>: Per file keywords. (line 23)
8185 * M-<TAB> <2>: Editing and debugging formulas.
8187 * M-<TAB> <3>: Property syntax. (line 46)
8188 * M-<TAB> <4>: Completion. (line 10)
8189 * M-<TAB>: Setting tags. (line 6)
8190 * M-<up> <1>: Built-in table editor.
8192 * M-<up>: Editing and debugging formulas.
8194 * M-S-<down> <1>: Plain lists. (line 66)
8195 * M-S-<down> <2>: Structure editing. (line 40)
8196 * M-S-<down> <3>: Editing and debugging formulas.
8198 * M-S-<down>: Built-in table editor.
8200 * M-S-<left> <1>: Structure editing. (line 31)
8201 * M-S-<left> <2>: The date/time prompt.
8203 * M-S-<left> <3>: Built-in table editor.
8205 * M-S-<left>: Plain lists. (line 72)
8206 * M-S-<RET> <1>: Checkboxes. (line 54)
8207 * M-S-<RET> <2>: Plain lists. (line 59)
8208 * M-S-<RET>: Structure editing. (line 22)
8209 * M-S-<right> <1>: Built-in table editor.
8211 * M-S-<right> <2>: Structure editing. (line 34)
8212 * M-S-<right> <3>: Plain lists. (line 72)
8213 * M-S-<right>: The date/time prompt.
8215 * M-S-<up> <1>: Structure editing. (line 37)
8216 * M-S-<up> <2>: Editing and debugging formulas.
8218 * M-S-<up> <3>: Built-in table editor.
8220 * M-S-<up>: Plain lists. (line 66)
8221 * mouse-1 <1>: Handling links. (line 72)
8222 * mouse-1 <2>: Agenda commands. (line 33)
8223 * mouse-1: The date/time prompt.
8225 * mouse-2 <1>: Handling links. (line 72)
8226 * mouse-2: Agenda commands. (line 33)
8227 * mouse-3 <1>: Agenda commands. (line 28)
8228 * mouse-3: Handling links. (line 77)
8229 * n <1>: Using column view. (line 30)
8230 * n: Agenda commands. (line 19)
8231 * O: Agenda commands. (line 181)
8232 * o: Agenda commands. (line 65)
8233 * p: Using column view. (line 30)
8234 * P: Agenda commands. (line 141)
8235 * p: Agenda commands. (line 20)
8236 * q <1>: Using column view. (line 17)
8237 * q: Agenda commands. (line 239)
8238 * r <1>: Agenda commands. (line 80)
8239 * r: Global TODO list. (line 22)
8240 * S: Agenda commands. (line 207)
8241 * s: Agenda commands. (line 87)
8242 * S-<down> <1>: Priorities. (line 23)
8243 * S-<down> <2>: The date/time prompt.
8245 * S-<down> <3>: Plain lists. (line 62)
8246 * S-<down> <4>: Creating timestamps. (line 40)
8247 * S-<down> <5>: Agenda commands. (line 150)
8248 * S-<down>: Editing and debugging formulas.
8250 * S-<left> <1>: Editing and debugging formulas.
8252 * S-<left> <2>: TODO basics. (line 26)
8253 * S-<left> <3>: Multiple sets in one file.
8255 * S-<left> <4>: Property syntax. (line 62)
8256 * S-<left> <5>: Using column view. (line 26)
8257 * S-<left> <6>: Agenda commands. (line 168)
8258 * S-<left> <7>: Creating timestamps. (line 35)
8259 * S-<left>: The date/time prompt.
8261 * S-<RET>: Built-in table editor.
8263 * S-<right> <1>: Agenda commands. (line 160)
8264 * S-<right> <2>: TODO basics. (line 26)
8265 * S-<right> <3>: The date/time prompt.
8267 * S-<right> <4>: Editing and debugging formulas.
8269 * S-<right> <5>: Multiple sets in one file.
8271 * S-<right> <6>: Property syntax. (line 62)
8272 * S-<right> <7>: Using column view. (line 26)
8273 * S-<right>: Creating timestamps. (line 35)
8274 * S-<TAB> <1>: Built-in table editor.
8276 * S-<TAB>: Visibility cycling. (line 22)
8277 * S-<up> <1>: Creating timestamps. (line 40)
8278 * S-<up> <2>: Agenda commands. (line 144)
8279 * S-<up> <3>: Plain lists. (line 62)
8280 * S-<up> <4>: The date/time prompt.
8282 * S-<up> <5>: Editing and debugging formulas.
8284 * S-<up>: Priorities. (line 23)
8285 * S-M-<left>: Using column view. (line 58)
8286 * S-M-<RET>: TODO basics. (line 56)
8287 * S-M-<right>: Using column view. (line 55)
8288 * t: Agenda commands. (line 111)
8289 * T: Agenda commands. (line 124)
8290 * v: Using column view. (line 39)
8291 * w: Agenda commands. (line 66)
8292 * X: Agenda commands. (line 184)
8293 * x: Agenda commands. (line 240)
8294 * y: Agenda commands. (line 66)
8300 Node: Introduction
\x7f13081
8301 Node: Summary
\x7f13496
8302 Node: Installation
\x7f16623
8303 Node: Activation
\x7f18001
8304 Node: Feedback
\x7f19238
8305 Node: Document structure
\x7f21307
8306 Node: Outlines
\x7f22199
8307 Node: Headlines
\x7f22864
8308 Ref: Headlines-Footnote-1
\x7f23868
8309 Node: Visibility cycling
\x7f23979
8310 Ref: Visibility cycling-Footnote-1
\x7f26189
8311 Ref: Visibility cycling-Footnote-2
\x7f26247
8312 Ref: Visibility cycling-Footnote-3
\x7f26297
8313 Node: Motion
\x7f26567
8314 Node: Structure editing
\x7f27521
8315 Node: Archiving
\x7f30515
8316 Node: ARCHIVE tag
\x7f31073
8317 Node: Moving subtrees
\x7f32866
8318 Ref: Moving subtrees-Footnote-1
\x7f34413
8319 Node: Sparse trees
\x7f34700
8320 Ref: Sparse trees-Footnote-1
\x7f36835
8321 Ref: Sparse trees-Footnote-2
\x7f37017
8322 Node: Plain lists
\x7f37132
8323 Ref: Plain lists-Footnote-1
\x7f41329
8324 Ref: Plain lists-Footnote-2
\x7f41687
8325 Node: Drawers
\x7f41868
8326 Node: orgstruct-mode
\x7f42706
8327 Node: Tables
\x7f43606
8328 Node: Built-in table editor
\x7f44187
8329 Node: Narrow columns
\x7f51593
8330 Ref: Narrow columns-Footnote-1
\x7f53528
8331 Node: Column groups
\x7f53574
8332 Node: orgtbl-mode
\x7f55107
8333 Node: The spreadsheet
\x7f55910
8334 Node: References
\x7f56997
8335 Ref: References-Footnote-1
\x7f61461
8336 Node: Formula syntax for Calc
\x7f61750
8337 Node: Formula syntax for Lisp
\x7f64207
8338 Node: Field formulas
\x7f65925
8339 Node: Column formulas
\x7f67233
8340 Node: Editing and debugging formulas
\x7f68832
8341 Node: Updating the table
\x7f72985
8342 Node: Advanced features
\x7f74038
8343 Node: Hyperlinks
\x7f78563
8344 Node: Link format
\x7f79341
8345 Node: Internal links
\x7f80634
8346 Ref: Internal links-Footnote-1
\x7f82559
8347 Node: Radio targets
\x7f82694
8348 Node: External links
\x7f83394
8349 Node: Handling links
\x7f85798
8350 Ref: Handling links-Footnote-1
\x7f91095
8351 Ref: Handling links-Footnote-2
\x7f91332
8352 Node: Using links outside Org-mode
\x7f91406
8353 Node: Link abbreviations
\x7f91916
8354 Node: Search options
\x7f93609
8355 Ref: Search options-Footnote-1
\x7f95389
8356 Node: Custom searches
\x7f95470
8357 Node: TODO items
\x7f96501
8358 Node: TODO basics
\x7f97539
8359 Node: TODO extensions
\x7f99744
8360 Node: Workflow states
\x7f100688
8361 Ref: Workflow states-Footnote-1
\x7f101863
8362 Node: TODO types
\x7f101956
8363 Ref: TODO types-Footnote-1
\x7f103539
8364 Node: Multiple sets in one file
\x7f103621
8365 Node: Fast access to TODO states
\x7f105241
8366 Node: Per file keywords
\x7f106384
8367 Ref: Per file keywords-Footnote-1
\x7f107686
8368 Node: Faces for TODO keywords
\x7f107887
8369 Node: Progress logging
\x7f108593
8370 Node: Closing items
\x7f109024
8371 Ref: Closing items-Footnote-1
\x7f109958
8372 Ref: Closing items-Footnote-2
\x7f110027
8373 Node: Tracking TODO state changes
\x7f110100
8374 Node: Priorities
\x7f111246
8375 Ref: Priorities-Footnote-1
\x7f112896
8376 Node: Breaking down tasks
\x7f112966
8377 Ref: Breaking down tasks-Footnote-1
\x7f113486
8378 Node: Checkboxes
\x7f113582
8379 Node: Tags
\x7f116431
8380 Node: Tag inheritance
\x7f117203
8381 Node: Setting tags
\x7f118140
8382 Ref: Setting tags-Footnote-1
\x7f122663
8383 Ref: Setting tags-Footnote-2
\x7f122775
8384 Node: Tag searches
\x7f122858
8385 Node: Properties and columns
\x7f125575
8386 Node: Property syntax
\x7f126680
8387 Node: Special properties
\x7f129101
8388 Node: Property searches
\x7f130017
8389 Node: Column view
\x7f130672
8390 Node: Defining columns
\x7f131839
8391 Node: Scope of column definitions
\x7f132237
8392 Node: Column attributes
\x7f133159
8393 Node: Using column view
\x7f135407
8394 Node: Property API
\x7f137394
8395 Node: Timestamps
\x7f137748
8396 Node: Time stamps
\x7f138159
8397 Ref: Time stamps-Footnote-1
\x7f140513
8398 Node: Creating timestamps
\x7f140629
8399 Node: The date/time prompt
\x7f142703
8400 Ref: The date/time prompt-Footnote-1
\x7f144691
8401 Node: Custom time format
\x7f144797
8402 Node: Deadlines and scheduling
\x7f146489
8403 Ref: Deadlines and scheduling-Footnote-1
\x7f148562
8404 Node: Inserting deadline/schedule
\x7f148717
8405 Node: Repeated tasks
\x7f149655
8406 Node: Clocking work time
\x7f151294
8407 Ref: Clocking work time-Footnote-1
\x7f155650
8408 Ref: Clocking work time-Footnote-2
\x7f155728
8409 Node: Remember
\x7f155854
8410 Node: Setting up remember
\x7f156736
8411 Node: Remember templates
\x7f157339
8412 Ref: Remember templates-Footnote-1
\x7f160856
8413 Ref: Remember templates-Footnote-2
\x7f161039
8414 Node: Storing notes
\x7f161137
8415 Ref: Storing notes-Footnote-1
\x7f163616
8416 Node: Agenda views
\x7f163718
8417 Node: Agenda files
\x7f165669
8418 Ref: Agenda files-Footnote-1
\x7f166761
8419 Ref: Agenda files-Footnote-2
\x7f166910
8420 Node: Agenda dispatcher
\x7f167103
8421 Node: Built-in agenda views
\x7f168802
8422 Node: Weekly/Daily agenda
\x7f169384
8423 Node: Global TODO list
\x7f172328
8424 Node: Matching tags and properties
\x7f174608
8425 Node: Timeline
\x7f175699
8426 Node: Stuck projects
\x7f176373
8427 Node: Presentation and sorting
\x7f178226
8428 Node: Categories
\x7f179019
8429 Ref: Categories-Footnote-1
\x7f179730
8430 Node: Time-of-day specifications
\x7f180050
8431 Node: Sorting of agenda items
\x7f182023
8432 Node: Agenda commands
\x7f183307
8433 Node: Custom agenda views
\x7f190685
8434 Node: Storing searches
\x7f191406
8435 Node: Block agenda
\x7f193320
8436 Node: Setting Options
\x7f194552
8437 Node: Exporting Agenda Views
\x7f197293
8438 Ref: Exporting Agenda Views-Footnote-1
\x7f201579
8439 Ref: Exporting Agenda Views-Footnote-2
\x7f201636
8440 Node: Extracting Agenda Information for other programs
\x7f201822
8441 Node: Embedded LaTeX
\x7f205950
8442 Ref: Embedded LaTeX-Footnote-1
\x7f207044
8443 Node: Math symbols
\x7f207234
8444 Node: Subscripts and Superscripts
\x7f208001
8445 Node: LaTeX fragments
\x7f208847
8446 Ref: LaTeX fragments-Footnote-1
\x7f211080
8447 Ref: LaTeX fragments-Footnote-2
\x7f211341
8448 Node: Processing LaTeX fragments
\x7f211475
8449 Node: CDLaTeX mode
\x7f212423
8450 Ref: CDLaTeX mode-Footnote-1
\x7f214909
8451 Node: Exporting
\x7f215057
8452 Node: ASCII export
\x7f216524
8453 Node: HTML export
\x7f218025
8454 Node: HTML Export commands
\x7f218651
8455 Node: Quoting HTML tags
\x7f220438
8456 Node: Links
\x7f221073
8457 Node: Images
\x7f221770
8458 Ref: Images-Footnote-1
\x7f222641
8459 Node: CSS support
\x7f222702
8460 Ref: CSS support-Footnote-1
\x7f224021
8461 Node: LaTeX export
\x7f224134
8462 Node: LaTeX export commands
\x7f224458
8463 Node: Quoting LaTeX code
\x7f225620
8464 Node: XOXO export
\x7f226125
8465 Node: iCalendar export
\x7f226565
8466 Node: Text interpretation
\x7f227784
8467 Node: Comment lines
\x7f228375
8468 Node: Initial text
\x7f228770
8469 Node: Footnotes
\x7f230439
8470 Node: Enhancing text
\x7f231230
8471 Ref: Enhancing text-Footnote-1
\x7f233099
8472 Node: Export options
\x7f233189
8473 Node: Publishing
\x7f235542
8474 Ref: Publishing-Footnote-1
\x7f236503
8475 Ref: Publishing-Footnote-2
\x7f236647
8476 Node: Configuration
\x7f236798
8477 Node: Project alist
\x7f237516
8478 Node: Sources and destinations
\x7f238582
8479 Node: Selecting files
\x7f239312
8480 Node: Publishing action
\x7f240060
8481 Node: Publishing options
\x7f241394
8482 Node: Publishing links
\x7f243769
8483 Node: Project page index
\x7f245282
8484 Node: Sample configuration
\x7f246060
8485 Node: Simple example
\x7f246552
8486 Node: Complex example
\x7f247225
8487 Node: Triggering publication
\x7f249301
8488 Node: Miscellaneous
\x7f249986
8489 Node: Completion
\x7f250620
8490 Node: Customization
\x7f252290
8491 Node: In-buffer settings
\x7f252873
8492 Node: The very busy C-c C-c key
\x7f258408
8493 Node: Clean view
\x7f260263
8494 Node: TTY keys
\x7f262840
8495 Node: Interaction
\x7f264450
8496 Node: Cooperation
\x7f264847
8497 Node: Conflicts
\x7f267723
8498 Node: Bugs
\x7f269726
8499 Node: Extensions and Hacking
\x7f271222
8500 Node: Extensions
\x7f271947
8501 Node: Adding hyperlink types
\x7f274209
8502 Node: Tables in arbitrary syntax
\x7f277871
8503 Node: Radio tables
\x7f278960
8504 Node: A LaTeX example
\x7f281463
8505 Ref: A LaTeX example-Footnote-1
\x7f285109
8506 Ref: A LaTeX example-Footnote-2
\x7f285257
8507 Node: Translator functions
\x7f285692
8508 Ref: Translator functions-Footnote-1
\x7f288801
8509 Node: Dynamic blocks
\x7f288889
8510 Node: Special agenda views
\x7f290861
8511 Node: Using the property API
\x7f294106
8512 Node: History and Acknowledgments
\x7f295587
8513 Node: Index
\x7f302163
8514 Node: Key Index
\x7f336794