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.12).
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.12).
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.
738 With prefix arg, kill N sequential subtrees.
741 Copy subtree to kill ring. With prefix arg, copy N sequential
745 Yank subtree from kill ring. This does modify the level of the
746 subtree to make sure the tree fits in nicely at the yank position.
747 The yank level can also be specified with a prefix arg, or by
748 yanking after a headline marker like `****'.
751 Sort same-level entries. When there is an active region, all
752 entries in the region will be sorted. Otherwise the children of
753 the current headline are sorted. The command prompts for the
754 sorting method, which can be alphabetically, numerically, by time
755 (using the first time stamp in each entry), by priority, and each
756 of these in reverse order. With a `C-u' prefix, sorting will be
757 case-sensitive. With two `C-u C-u' prefixes, duplicate entries
758 will also be removed.
760 When there is an active region (transient-mark-mode), promotion and
761 demotion work on all headlines in the region. To select a region of
762 headlines, it is best to place both point and mark at the beginning of a
763 line, mark at the beginning of the first headline, and point at the line
764 just after the last headline to change. Note that when the cursor is
765 inside a table (*note Tables::), the Meta-Cursor keys have different
769 File: org, Node: Archiving, Next: Sparse trees, Prev: Structure editing, Up: Document structure
774 When a project represented by a (sub)tree is finished, you may want to
775 move the tree out of the way and to stop it from contributing to the
776 agenda. Org-mode knows two ways of archiving. You can mark a tree with
777 the ARCHIVE tag, or you can move an entire (sub)tree to a different
782 * ARCHIVE tag:: Marking a tree as inactive
783 * Moving subtrees:: Moving a tree to an archive file
786 File: org, Node: ARCHIVE tag, Next: Moving subtrees, Prev: Archiving, Up: Archiving
788 2.6.1 The ARCHIVE tag
789 ---------------------
791 A headline that is marked with the ARCHIVE tag (*note Tags::) stays at
792 its location in the outline tree, but behaves in the following way:
793 - It does not open when you attempt to do so with a visibility
794 cycling command (*note Visibility cycling::). You can force
795 cycling archived subtrees with `C-<TAB>', or by setting the option
796 `org-cycle-open-archived-trees'. Also normal outline commands like
797 `show-all' will open archived subtrees.
799 - During sparse tree construction (*note Sparse trees::), matches in
800 archived subtrees are not exposed, unless you configure the option
801 `org-sparse-tree-open-archived-trees'.
803 - During agenda view construction (*note Agenda views::), the
804 content of archived trees is ignored unless you configure the
805 option `org-agenda-skip-archived-trees'.
807 - Archived trees are not exported (*note Exporting::), only the
808 headline is. Configure the details using the variable
809 `org-export-with-archived-trees'.
811 The following commands help managing the ARCHIVE tag:
814 Toggle the ARCHIVE tag for the current headline. When the tag is
815 set, the headline changes to a shadowish face, and the subtree
819 Check if any direct children of the current headline should be
820 archived. To do this, each subtree is checked for open TODO
821 entries. If none are found, the command offers to set the ARCHIVE
822 tag for the child. If the cursor is _not_ on a headline when this
823 command is invoked, the level 1 trees will be checked.
826 Cycle a tree even if it is tagged with ARCHIVE.
829 File: org, Node: Moving subtrees, Prev: ARCHIVE tag, Up: Archiving
831 2.6.2 Moving subtrees
832 ---------------------
834 Once an entire project is finished, you may want to move it to a
835 different location, either in the current file, or even in a different
836 file, the archive file.
839 Archive the subtree starting at the cursor position to the location
840 given by `org-archive-location'. Context information that could be
841 lost like the file name, the category, inherited tags, and the todo
842 state will be store as properties in the entry.
845 Check if any direct children of the current headline could be
846 moved to the archive. To do this, each subtree is checked for
847 open TODO entries. If none are found, the command offers to move
848 it to the archive location. If the cursor is _not_ on a headline
849 when this command is invoked, the level 1 trees will be checked.
851 The default archive location is a file in the same directory as the
852 current file, with the name derived by appending `_archive' to the
853 current file name. For information and examples on how to change this,
854 see the documentation string of the variable `org-archive-location'.
855 There is also an in-buffer option for setting this variable, for
860 If you would like to have a special ARCHIVE location for a single entry
861 or a (sub)tree, give the entry an `:ARCHIVE:' property with the
862 location as the value (*note Properties and columns::).
864 ---------- Footnotes ----------
866 (1) If there are several such lines in the buffer, each will be
867 valid for the entries below it. The first will also apply to any text
868 before it. This method is only kept for backward compatibility. The
869 preferred methods for setting multiple archive locations is using a
873 File: org, Node: Sparse trees, Next: Plain lists, Prev: Archiving, Up: Document structure
878 An important feature of Org-mode is the ability to construct _sparse
879 trees_ for selected information in an outline tree. A sparse tree
880 means that the entire document is folded as much as possible, but the
881 selected information is made visible along with the headline structure
882 above it(1). Just try it out and you will see immediately how it works.
884 Org-mode contains several commands creating such trees, all these
885 commands can be accessed through a dispatcher:
888 This prompts for an extra key to select a sparse-tree creating
892 Occur. Prompts for a regexp and shows a sparse tree with all
893 matches. If the match is in a headline, the headline is made
894 visible. If the match is in the body of an entry, headline and
895 body are made visible. In order to provide minimal context, also
896 the full hierarchy of headlines above the match is shown, as well
897 as the headline following the match. Each match is also
898 highlighted; the highlights disappear when the buffer is changed
899 by an editing command, or by pressing `C-c C-c'. When called with
900 a `C-u' prefix argument, previous highlights are kept, so several
901 calls to this command can be stacked.
902 For frequently used sparse trees of specific search strings, you can
903 use the variable `org-agenda-custom-commands' to define fast keyboard
904 access to specific sparse trees. These commands will then be
905 accessible through the agenda dispatcher (*note Agenda dispatcher::).
908 (setq org-agenda-custom-commands
909 '(("f" occur-tree "FIXME")))
911 will define the key `C-c a f' as a shortcut for creating a sparse tree
912 matching the string `FIXME'.
914 The other sparse tree commands select headings based on TODO
915 keywords, tags, or properties and will be discussed later in this
918 To print a sparse tree, you can use the Emacs command
919 `ps-print-buffer-with-faces' which does not print invisible parts of
920 the document (2). Or you can use the command `C-c C-e v' to export
921 only the visible part of the document and print the resulting file.
923 ---------- Footnotes ----------
925 (1) See also the variables `org-show-hierarchy-above',
926 `org-show-following-heading', and `org-show-siblings' for detailed
927 control on how much context is shown around each match.
929 (2) This does not work under XEmacs, because XEmacs uses selective
930 display for outlining, not text properties.
933 File: org, Node: Plain lists, Next: Drawers, Prev: Sparse trees, Up: Document structure
938 Within an entry of the outline tree, hand-formatted lists can provide
939 additional structure. They also provide a way to create lists of
940 checkboxes (*note Checkboxes::). Org-mode supports editing such lists,
941 and the HTML exporter (*note Exporting::) does parse and format them.
943 Org-mode knows ordered and unordered lists. Unordered list items
944 start with `-', `+', or `*'(1) as bullets. Ordered list items start
945 with `1.' or `1)'. Items belonging to the same list must have the same
946 indentation on the first line. In particular, if an ordered list
947 reaches number `10.', then the 2-digit numbers must be written
948 left-aligned with the other numbers in the list. Indentation also
949 determines the end of a list item. It ends before the next line that
950 is indented like the bullet/number, or less. Empty lines are part of
951 the previous item, so you can have several paragraphs in one item. If
952 you would like an empty line to terminate all currently open plain
953 lists, configure the variable `org-empty-line-terminates-plain-lists'.
957 My favorite scenes are (in this order)
958 1. The attack of the Rohirrim
959 2. Eowyns fight with the witch king
960 + this was already my favorite scene in the book
961 + I really like Miranda Otto.
962 3. Peter Jackson being shot by Legolas
964 He makes a really funny face when it happens.
965 But in the end, not individual scenes matter but the film as a whole.
967 Org-mode supports these lists by tuning filling and wrapping
968 commands to deal with them correctly(2).
970 The following commands act on items when the cursor is in the first
971 line of an item (the line with the bullet or number).
974 Items can be folded just like headline levels if you set the
975 variable `org-cycle-include-plain-lists'. The level of an item is
976 then given by the indentation of the bullet/number. Items are
977 always subordinate to real headlines, however; the hierarchies
978 remain completely separated.
980 If `org-cycle-include-plain-lists' has not been set, <TAB> fixes
981 the indentation of the curent line in a heuristic way.
984 Insert new item at current level. With prefix arg, force a new
985 heading (*note Structure editing::). If this command is used in
986 the middle of a line, the line is _split_ and the rest of the line
987 becomes the new item. If this command is executed in the
988 _whitespace before a bullet or number_, the new item is created
989 _before_ the current item. If the command is executed in the
990 white space before the text that is part of an item but does not
991 contain the bullet, a bullet is added to the current line.
994 Insert a new item with a checkbox (*note Checkboxes::).
998 Jump to the previous/next item in the current list.
1002 Move the item including subitems up/down (swap with previous/next
1003 item of same indentation). If the list is ordered, renumbering is
1008 Decrease/increase the indentation of the item, including subitems.
1009 Initially, the item tree is selected based on current indentation.
1010 When these commands are executed several times in direct
1011 succession, the initially selected region is used, even if the new
1012 indentation would imply a different hierarchy. To use the new
1013 hierarchy, break the command chain with a cursor motion or so.
1016 If there is a checkbox (*note Checkboxes::) in the item line,
1017 toggle the state of the checkbox. If not, make this command makes
1018 sure that all the items on this list level use the same bullet.
1019 Furthermore, if this is an ordered list, make sure the numbering
1023 Cycle the entire list level through the different itemize/enumerate
1024 bullets (`-', `+', `*', `1.', `1)'). With prefix arg, select the
1025 nth bullet from this list.
1027 ---------- Footnotes ----------
1029 (1) When using `*' as a bullet, lines must be indented or they will
1030 be seen as top-level headlines. Also, when you are hiding leading
1031 stars to get a clean outline view, plain list items starting with a
1032 star are visually indistinguishable from true headlines. In short:
1033 even though `*' is supported, it may be better not to use it for plain
1036 (2) Org-mode only changes the filling settings for Emacs. For
1037 XEmacs, you should use Kyle E. Jones' `filladapt.el'. To turn this on,
1038 put into `.emacs': `(require 'filladapt)'
1041 File: org, Node: Drawers, Next: orgstruct-mode, Prev: Plain lists, Up: Document structure
1046 Sometimes you want to keep information associated with an entry, but you
1047 normally don't want to see it. For this, Org-mode has _drawers_.
1048 Drawers need to be configured with the variable `org-drawers', and look
1051 ** This is a headline
1052 Still outside the drawer
1054 This is inside the drawer.
1058 Visibility cycling (*note Visibility cycling::) on the headline will
1059 hide and show the entry, but keep the drawer collapsed to a single line.
1060 In order to look inside the drawer, you need to move the cursor to the
1061 drawer line and press <TAB> there. Org-mode uses a drawer for storing
1062 properties (*note Properties and columns::).
1065 File: org, Node: orgstruct-mode, Prev: Drawers, Up: Document structure
1067 2.10 The Orgstruct minor mode
1068 =============================
1070 If you like the intuitive way the Org-mode structure editing and list
1071 formatting works, you might want to use these commands in other modes
1072 like text-mode or mail-mode as well. The minor mode Orgstruct-mode
1073 makes this possible. You can always toggle the mode with `M-x
1074 orgstruct-mode'. To turn it on by default, for example in mail mode,
1077 (add-hook 'mail-mode-hook 'turn-on-orgstruct)
1079 When this mode is active and the cursor is on a line that looks to
1080 Org-mode like a headline of the first line of a list item, most
1081 structure editing commands will work, even if the same keys normally
1082 have different functionality in the major mode you are using. If the
1083 cursor is not in one of those special lines, Orgstruct-mode lurks
1084 silently in the shadow.
1087 File: org, Node: Tables, Next: Hyperlinks, Prev: Document structure, Up: Top
1092 Org-mode has a very fast and intuitive table editor built-in.
1093 Spreadsheet-like calculations are supported in connection with the
1094 Emacs `calc' package.
1098 * Built-in table editor:: Simple tables
1099 * Narrow columns:: Stop wasting space in tables
1100 * Column groups:: Grouping to trigger vertical lines
1101 * orgtbl-mode:: The table editor as minor mode
1102 * The spreadsheet:: The table editor has spreadsheet capabilities.
1105 File: org, Node: Built-in table editor, Next: Narrow columns, Prev: Tables, Up: Tables
1107 3.1 The built-in table editor
1108 =============================
1110 Org-mode makes it easy to format tables in plain ASCII. Any line with
1111 `|' as the first non-whitespace character is considered part of a
1112 table. `|' is also the column separator. A table might look like this:
1114 | Name | Phone | Age |
1115 |-------+-------+-----|
1116 | Peter | 1234 | 17 |
1117 | Anna | 4321 | 25 |
1119 A table is re-aligned automatically each time you press <TAB> or
1120 <RET> or `C-c C-c' inside the table. <TAB> also moves to the next
1121 field (<RET> to the next row) and creates new table rows at the end of
1122 the table or before horizontal lines. The indentation of the table is
1123 set by the first line. Any line starting with `|-' is considered as a
1124 horizontal separator line and will be expanded on the next re-align to
1125 span the whole table width. So, to create the above table, you would
1131 and then press <TAB> to align the table and start filling in fields.
1133 When typing text into a field, Org-mode treats <DEL>, <Backspace>,
1134 and all character keys in a special way, so that inserting and deleting
1135 avoids shifting other fields. Also, when typing _immediately after the
1136 cursor was moved into a new field with `<TAB>', `S-<TAB>' or `<RET>'_,
1137 the field is automatically made blank. If this behavior is too
1138 unpredictable for you, configure the variables
1139 `org-enable-table-editor' and `org-table-auto-blank-field'.
1141 Creation and conversion
1142 .......................
1145 Convert the active region to table. If every line contains at
1146 least one TAB character, the function assumes that the material is
1147 tab separated. If every line contains a comma, comma-separated
1148 values (CSV) are assumed. If not, lines are split at whitespace
1149 into fields. You can use a prefix argument to force a specific
1150 separator: `C-u' forces CSV, `C-u C-u' forces TAB, and a numeric
1151 argument N indicates that at least N consequtive spaces, or
1152 alternatively a TAB will be the separator.
1153 If there is no active region, this command creates an empty
1154 Org-mode table. But it's easier just to start typing, like
1155 `|Name|Phone|Age <RET> |- <TAB>'.
1157 Re-aligning and field motion
1158 ............................
1161 Re-align the table without moving the cursor.
1164 Re-align the table, move to the next field. Creates a new row if
1168 Re-align, move to previous field.
1171 Re-align the table and move down to next row. Creates a new row if
1172 necessary. At the beginning or end of a line, <RET> still does
1173 NEWLINE, so it can be used to split a table.
1175 Column and row editing
1176 ......................
1180 Move the current column left/right.
1183 Kill the current column.
1186 Insert a new column to the left of the cursor position.
1190 Move the current row up/down.
1193 Kill the current row or horizontal line.
1196 Insert a new row above (with arg: below) the current row.
1199 Insert a horizontal line below current row. With prefix arg, the
1200 line is created above the current line.
1203 Sort the table lines in the region. The position of point
1204 indicates the column to be used for sorting, and the range of
1205 lines is the range between the nearest horizontal separator lines,
1206 or the entire table. If point is before the first column, you
1207 will be prompted for the sorting column. If there is an active
1208 region, the mark specifies the first line and the sorting column,
1209 while point should be in the last line to be included into the
1210 sorting. The command prompts for the sorting type
1211 (alphabetically, numerically, or by time). When called with a
1212 prefix argument, alphabetic sorting will be case-sensitive.
1218 Copy a rectangular region from a table to a special clipboard.
1219 Point and mark determine edge fields of the rectangle. The
1220 process ignores horizontal separator lines.
1223 Copy a rectangular region from a table to a special clipboard, and
1224 blank all fields in the rectangle. So this is the "cut" operation.
1227 Paste a rectangular region into a table. The upper right corner
1228 ends up in the current field. All involved fields will be
1229 overwritten. If the rectangle does not fit into the present table,
1230 the table is enlarged as needed. The process ignores horizontal
1234 Wrap several fields in a column like a paragraph. If there is an
1235 active region, and both point and mark are in the same column, the
1236 text in the column is wrapped to minimum width for the given
1237 number of lines. A prefix ARG may be used to change the number of
1238 desired lines. If there is no region, the current field is split
1239 at the cursor position and the text fragment to the right of the
1240 cursor is prepended to the field one line down. If there is no
1241 region, but you specify a prefix ARG, the current field is made
1242 blank, and the content is appended to the field above.
1248 Sum the numbers in the current column, or in the rectangle defined
1249 by the active region. The result is shown in the echo area and can
1250 be inserted with `C-y'.
1253 When current field is empty, copy from first non-empty field above.
1254 When not empty, copy current field down to next row and move cursor
1255 along with it. Depending on the variable
1256 `org-table-copy-increment', integer field values will be
1257 incremented during copy. This key is also used by CUA-mode (*note
1264 Edit the current field in a separate window. This is useful for
1265 fields that are not fully visible (*note Narrow columns::). When
1266 called with a `C-u' prefix, just make the full field visible, so
1267 that it can be edited in place.
1270 This is an alias for `C-u C-c `' to make the current field fully
1273 `M-x org-table-import'
1274 Import a file as a table. The table should be TAB- or whitespace
1275 separated. Useful, for example, to import an Excel table or data
1276 from a database, because these programs generally can write
1277 TAB-separated text files. This command works by inserting the
1278 file into the buffer and then converting the region to a table.
1279 Any prefix argument is passed on to the converter, which uses it
1280 to determine the separator.
1283 Tables can also be imported by pasting tabular text into the
1284 org-mode buffer, selecting the pasted text with `C-x C-x' and then
1285 using the `C-c |' command (see above under Creation and conversion.
1287 `M-x org-table-export'
1288 Export the table as a TAB-separated file. Useful for data
1289 exchange with, for example, Excel or database programs.
1291 If you don't like the automatic table editor because it gets in your
1292 way on lines which you would like to start with `|', you can turn it
1295 (setq org-enable-table-editor nil)
1297 Then the only table command that still works is `C-c C-c' to do a
1301 File: org, Node: Narrow columns, Next: Column groups, Prev: Built-in table editor, Up: Tables
1306 The width of columns is automatically determined by the table editor.
1307 Sometimes a single field or a few fields need to carry more text,
1308 leading to inconveniently wide columns. To limit(1) the width of a
1309 column, one field anywhere in the column may contain just the string
1310 `<N>' where `N' is an integer specifying the width of the column in
1311 characters. The next re-align will then set the width of this column
1312 to no more than this value.
1314 |---+------------------------------| |---+--------|
1316 | 1 | one | | 1 | one |
1317 | 2 | two | ----\ | 2 | two |
1318 | 3 | This is a long chunk of text | ----/ | 3 | This=> |
1319 | 4 | four | | 4 | four |
1320 |---+------------------------------| |---+--------|
1322 Fields that are wider become clipped and end in the string `=>'. Note
1323 that the full text is still in the buffer, it is only invisible. To
1324 see the full text, hold the mouse over the field - a tool-tip window
1325 will show the full content. To edit such a field, use the command `C-c
1326 `' (that is `C-c' followed by the backquote). This will open a new
1327 window with the full field. Edit it and finish with `C-c C-c'.
1329 When visiting a file containing a table with narrowed columns, the
1330 necessary character hiding has not yet happened, and the table needs to
1331 be aligned before it looks nice. Setting the option
1332 `org-startup-align-all-tables' will realign all tables in a file upon
1333 visiting, but also slow down startup. You can also set this option on
1334 a per-file basis with:
1339 ---------- Footnotes ----------
1341 (1) This feature does not work on XEmacs.
1344 File: org, Node: Column groups, Next: orgtbl-mode, Prev: Narrow columns, Up: Tables
1349 When Org-mode exports tables, it does so by default without vertical
1350 lines because that is visually more satisfying in general. Occasionally
1351 however, vertical lines can be useful to structure a table into groups
1352 of columns, much like horizontal lines can do for groups of rows. In
1353 order to specify column groups, you can use a special row where the
1354 first field contains only `/'. The further fields can either contain
1355 `<' to indicate that this column should start a group, `>' to indicate
1356 the end of a column, or `<>' to make a column a group of its own.
1357 Boundaries between colum groups will upon export be marked with
1358 vertical lines. Here is an example:
1360 | | N | N^2 | N^3 | N^4 | sqrt(n) | sqrt[4](N) |
1361 |---+----+-----+-----+-----+---------+------------|
1362 | / | <> | < | | > | < | > |
1363 | # | 1 | 1 | 1 | 1 | 1 | 1 |
1364 | # | 2 | 4 | 8 | 16 | 1.4142 | 1.1892 |
1365 | # | 3 | 9 | 27 | 81 | 1.7321 | 1.3161 |
1366 |---+----+-----+-----+-----+---------+------------|
1367 #+TBLFM: $3=$2^2::$4=$2^3::$5=$2^4::$6=sqrt($2)::$7=sqrt(sqrt(($2))
1369 It is also sufficient to just insert the colum group starters after
1370 every vertical line you'd like to have:
1372 | N | N^2 | N^3 | N^4 | sqrt(n) | sqrt[4](N) |
1373 |----+-----+-----+-----+---------+------------|
1377 File: org, Node: orgtbl-mode, Next: The spreadsheet, Prev: Column groups, Up: Tables
1379 3.4 The Orgtbl minor mode
1380 =========================
1382 If you like the intuitive way the Org-mode table editor works, you
1383 might also want to use it in other modes like text-mode or mail-mode.
1384 The minor mode Orgtbl-mode makes this possible. You can always toggle
1385 the mode with `M-x orgtbl-mode'. To turn it on by default, for example
1388 (add-hook 'mail-mode-hook 'turn-on-orgtbl)
1390 Furthermore, with some special setup, it is possible to maintain
1391 tables in arbitrary syntax with Orgtbl-mode. For example, it is
1392 possible to construct LaTeX tables with the underlying ease and power of
1393 Orgtbl-mode, including spreadsheet capabilities. For details, see
1394 *Note Tables in arbitrary syntax::.
1397 File: org, Node: The spreadsheet, Prev: orgtbl-mode, Up: Tables
1402 The table editor makes use of the Emacs `calc' package to implement
1403 spreadsheet-like capabilities. It can also evaluate Emacs Lisp forms to
1404 derive fields from other fields. While fully featured, Org-mode's
1405 implementation is not identical to other spreadsheets. For example,
1406 Org-mode knows the concept of a _column formula_ that will be applied
1407 to all non-header fields in a column without having to copy the formula
1408 to each relevant field.
1412 * References:: How to refer to another field or range
1413 * Formula syntax for Calc:: Using Calc to compute stuff
1414 * Formula syntax for Lisp:: Writing formulas in Emacs Lisp
1415 * Field formulas:: Formulas valid for a single field
1416 * Column formulas:: Formulas valid for an entire column
1417 * Editing and debugging formulas:: Fixing formulas
1418 * Updating the table:: Recomputing all dependent fields
1419 * Advanced features:: Field names, parameters and automatic recalc
1422 File: org, Node: References, Next: Formula syntax for Calc, Prev: The spreadsheet, Up: The spreadsheet
1427 To compute fields in the table from other fields, formulas must
1428 reference other fields or ranges. In Org-mode, fields can be referenced
1429 by name, by absolute coordinates, and by relative coordinates. To find
1430 out what the coordinates of a field are, press `C-c ?' in that field,
1431 or press `C-c }' to toggle the display of a grid.
1436 Formulas can reference the value of another field in two ways. Like in
1437 any other spreadsheet, you may reference fields with a letter/number
1438 combination like `B3', meaning the 2nd field in the 3rd row.
1440 Org-mode also uses another, more general operator that looks like this:
1443 Column references can be absolute like `1', `2',...`N', or relative to
1444 the current column like `+1' or `-2'.
1446 The row specification only counts data lines and ignores horizontal
1447 separator lines (hlines). You can use absolute row numbers `1'...`N',
1448 and row numbers relative to the current row like `+3' or `-1'. Or
1449 specify the row relative to one of the hlines: `I' refers to the first
1450 hline, `II' to the second etc. `-I' refers to the first such line
1451 above the current line, `+I' to the first such line below the current
1452 line. You can also write `III+2' which is the second data line after
1453 the third hline in the table. Relative row numbers like `-3' will not
1454 cross hlines if the current line is too close to the hline. Instead,
1455 the value directly at the hline is used.
1457 `0' refers to the current row and column. Also, if you omit either
1458 the column or the row part of the reference, the current row/column is
1461 Org-mode's references with _unsigned_ numbers are fixed references
1462 in the sense that if you use the same reference in the formula for two
1463 different fields, the same field will be referenced each time.
1464 Org-mode's references with _signed_ numbers are floating references
1465 because the same reference operator can reference different fields
1466 depending on the field being calculated by the formula.
1468 Here are a few examples:
1470 @2$3 2nd row, 3rd column
1472 $5 column 5 in the current row
1474 @2 current column, row 2
1475 @-1$-3 the field one row up, three columns to the left
1476 @-I$2 field just under hline above current row, column 2
1481 You may reference a rectangular range of fields by specifying two field
1482 references connected by two dots `..'. If both fields are in the
1483 current row, you may simply use `$2..$7', but if at least one field is
1484 in a different row, you need to use the general `@row$column' format at
1485 least for the first field (i.e the reference must start with `@' in
1486 order to be interpreted correctly). Examples:
1488 $1..$3 First three fields in the current row.
1489 $P..$Q Range, using column names (see under Advanced)
1490 @2$1..@4$3 6 fields between these two fields.
1491 A2..C4 Same as above.
1492 @-1$-2..@-1 3 numbers from the column to the left, 2 up to current row
1494 Range references return a vector of values that can be fed into Calc
1495 vector functions. Empty fields in ranges are normally suppressed, so
1496 that the vector contains only the non-empty fields (but see the `E'
1497 mode switch below). If there are no non-empty fields, `[0]' is
1498 returned to avoid syntax errors in formulas.
1503 `$name' is interpreted as the name of a column, parameter or constant.
1504 Constants are defined globally through the variable
1505 `org-table-formula-constants', and locally (for the file) through a
1508 #+CONSTANTS: c=299792458. pi=3.14 eps=2.4e-6
1510 Also properties (*note Properties and columns::) can be used as
1511 constants in table formulas: For a property `:XYZ:' use the name
1512 `$PROP_XYZ', and the property will be searched in the current outline
1513 entry and in the hierarchy above it. If you have the `constants.el'
1514 package, it will also be used to resolve constants, including natural
1515 constants like `$h' for Planck's constant, and units like `$km' for
1516 kilometers(1). Column names and parameters can be specified in special
1517 table lines. These are described below, see *Note Advanced features::.
1518 All names must start with a letter, and further consist of letters and
1521 ---------- Footnotes ----------
1523 (1) `Constant.el' can supply the values of constants in two
1524 different unit systems, `SI' and `cgs'. Which one is used depends on
1525 the value of the variable `constants-unit-system'. You can use the
1526 `#+STARTUP' options `constSI' and `constcgs' to set this value for the
1530 File: org, Node: Formula syntax for Calc, Next: Formula syntax for Lisp, Prev: References, Up: The spreadsheet
1532 3.5.2 Formula syntax for Calc
1533 -----------------------------
1535 A formula can be any algebraic expression understood by the Emacs
1536 `Calc' package. Note that `calc' has the non-standard convention that
1537 `/' has lower precedence than `*', so that `a/b*c' is interpreted as
1538 `a/(b*c)'. Before evaluation by `calc-eval' (*note calc-eval:
1539 (calc)Calling Calc from Your Programs.), variable substitution takes
1540 place according to the rules described above. The range vectors can be
1541 directly fed into the calc vector functions like `vmean' and `vsum'.
1543 A formula can contain an optional mode string after a semicolon.
1544 This string consists of flags to influence Calc and other modes during
1545 execution. By default, Org-mode uses the standard calc modes (precision
1546 12, angular units degrees, fraction and symbolic modes off. The display
1547 format, however, has been changed to `(float 5)' to keep tables
1548 compact. The default settings can be configured using the variable
1549 `org-calc-default-modes'.
1551 p20 switch the internal precision to 20 digits
1552 n3 s3 e2 f4 normal, scientific, engineering, or fixed display format
1553 D R angle modes: degrees, radians
1554 F S fraction and symbolic modes
1555 N interpret all fields as numbers, use 0 for non-numbers
1556 T force text interpretation
1557 E keep empty fields in ranges
1559 In addition, you may provide a `printf' format specifier to reformat
1560 the final result. A few examples:
1562 $1+$2 Sum of first and second field
1563 $1+$2;%.2f Same, format result to two decimals
1564 exp($2)+exp($1) Math functions can be used
1565 $0;%.1f Reformat current cell to 1 decimal
1566 ($3-32)*5/9 Degrees F -> C conversion
1567 $c/$1/$cm Hz -> cm conversion, using `constants.el'
1568 tan($1);Dp3s1 Compute in degrees, precision 3, display SCI 1
1569 sin($1);Dp3%.1e Same, but use printf specifier for display
1570 vmean($2..$7) Compute column range mean, using vector function
1571 vmean($2..$7);EN Same, but treat empty fields as 0
1572 taylor($3,x=7,2) taylor series of $3, at x=7, second degree
1574 Calc also contains a complete set of logical operations. For example
1576 if($1<20,teen,string("")) "teen" if age $1 less than 20, else empty
1579 File: org, Node: Formula syntax for Lisp, Next: Field formulas, Prev: Formula syntax for Calc, Up: The spreadsheet
1581 3.5.3 Emacs Lisp forms as formulas
1582 ----------------------------------
1584 It is also possible to write a formula in Emacs Lisp; this can be useful
1585 for string manipulation and control structures, if the Calc's
1586 functionality is not enough. If a formula starts with a single quote
1587 followed by an opening parenthesis, then it is evaluated as a lisp form.
1588 The evaluation should return either a string or a number. Just as with
1589 `calc' formulas, you can specify modes and a printf format after a
1590 semicolon. With Emacs Lisp forms, you need to be concious about the way
1591 field references are interpolated into the form. By default, a
1592 reference will be interpolated as a Lisp string (in double quotes)
1593 containing the field. If you provide the `N' mode switch, all
1594 referenced elements will be numbers (non-number fields will be zero) and
1595 interpolated as Lisp numbers, without quotes. If you provide the `L'
1596 flag, all fields will be interpolated literally, without quotes. I.e.,
1597 if you want a reference to be interpreted as a string by the Lisp form,
1598 enclode the reference operator itself in double quotes, like `"$3"'.
1599 Ranges are inserted as space-separated fields, so you can embed them in
1600 list or vector syntax. A few examples, note how the `N' mode is used
1601 when we do computations in lisp.
1603 Swap the first two characters of the content of column 1
1604 '(concat (substring $1 1 2) (substring $1 0 1) (substring $1 2))
1605 Add columns 1 and 2, equivalent to the Calc's `$1+$2'
1607 Compute the sum of columns 1-4, like Calc's `vsum($1..$4)'
1608 '(apply '+ '($1..$4));N
1611 File: org, Node: Field formulas, Next: Column formulas, Prev: Formula syntax for Lisp, Up: The spreadsheet
1613 3.5.4 Field formulas
1614 --------------------
1616 To assign a formula to a particular field, type it directly into the
1617 field, preceded by `:=', for example `:=$1+$2'. When you press <TAB>
1618 or <RET> or `C-c C-c' with the cursor still in the field, the formula
1619 will be stored as the formula for this field, evaluated, and the
1620 current field replaced with the result.
1622 Formulas are stored in a special line starting with `#+TBLFM:'
1623 directly below the table. If you typed the equation in the 4th field of
1624 the 3rd data line in the table, the formula will look like
1625 `@3$4=$1+$2'. When inserting/deleting/swapping column and rows with
1626 the appropriate commands, absolute references (but not relative ones)
1627 in stored formulas are modified in order to still reference the same
1628 field. Of cause this is not true if you edit the table structure with
1629 normal editing commands - then you must fix the equations yourself.
1631 Instead of typing an equation into the field, you may also use the
1635 Install a new formula for the current field. The command prompts
1636 for a formula, with default taken from the `#+TBLFM:' line, applies
1637 it to the current field and stores it.
1640 File: org, Node: Column formulas, Next: Editing and debugging formulas, Prev: Field formulas, Up: The spreadsheet
1642 3.5.5 Column formulas
1643 ---------------------
1645 Often in a table, the same formula should be used for all fields in a
1646 particular column. Instead of having to copy the formula to all fields
1647 in that column, org-mode allows to assign a single formula to an entire
1648 column. If the table contains horizontal separator hlines, everything
1649 before the first such line is considered part of the table _header_ and
1650 will not be modified by column formulas.
1652 To assign a formula to a column, type it directly into any field in
1653 the column, preceded by an equal sign, like `=$1+$2'. When you press
1654 <TAB> or <RET> or `C-c C-c' with the cursor still in the field, the
1655 formula will be stored as the formula for the current column, evaluated
1656 and the current field replaced with the result. If the field contains
1657 only `=', the previously stored formula for this column is used. For
1658 each column, Org-mode will only remember the most recently used
1659 formula. In the `TBLFM:' line, column formulas will look like
1662 Instead of typing an equation into the field, you may also use the
1666 Install a new formula for the current column and replace current
1667 field with the result of the formula. The command prompts for a
1668 formula, with default taken from the `#+TBLFM' line, applies it to
1669 the current field and stores it. With a numerical prefix (e.g.
1670 `C-5 C-c =') will apply it to that many consecutive fields in the
1674 File: org, Node: Editing and debugging formulas, Next: Updating the table, Prev: Column formulas, Up: The spreadsheet
1676 3.5.6 Editing and Debugging formulas
1677 ------------------------------------
1679 You can edit individual formulas in the minibuffer or directly in the
1680 field. Org-mode can also prepare a special buffer with all active
1681 formulas of a table. When offering a formula for editing, Org-mode
1682 converts references to the standard format (like `B3' or `D&') if
1683 possible. If you prefer to only work with the internal format (like
1684 `@3$2' or `$4'), configure the variable
1685 `org-table-use-standard-references'.
1689 Edit the formula associated with the current column/field in the
1690 minibuffer. See *Note Column formulas:: and *Note Field
1694 Re-insert the active formula (either a field formula, or a column
1695 formula) into the current field, so that you can edit it directly
1696 in the field. The advantage over editing in the minibuffer is
1697 that you can use the command `C-c ?'.
1700 While editing a formula in a table field, highlight the field(s)
1701 referenced by the reference at the cursor position in the formula.
1704 Toggle the display of row and column numbers for a table, using
1705 overlays. These are updated each time the table is aligned, you
1706 can force it with `C-c C-c'.
1709 Toggle the formula debugger on and off. See below.
1712 Edit all formulas for the current table in a special buffer, where
1713 the formulas will be displayed one per line. If the current field
1714 has an active formula, the cursor in the formula editor will mark
1715 it. While inside the special buffer, Org-mode will automatically
1716 highlight any field or range reference at the cursor position.
1717 You may edit, remove and add formulas, and use the following
1721 Exit the formula editor and store the modified formulas.
1722 With `C-u' prefix, also apply the new formulas to the entire
1726 Exit the formula editor without installing changes.
1729 Toggle all references in the formula editor between standard
1730 (like `B3') and internal (like `@3$2').
1733 Pretty-print or indent lisp formula at point. When in a line
1734 containing a lisp formula, format the formula according to
1735 Emacs Lisp rules. Another <TAB> collapses the formula back
1736 again. In the open formula, <TAB> re-indents just like in
1740 Complete Lisp symbols, just like in Emacs-lisp-mode.
1742 `S-<up>/<down>/<left>/<right>'
1743 Shift the reference at point. For example, if the reference
1744 is `B3' and you press `S-<right>', it will become `C3'. This
1745 also works for relative references, and for hline references.
1748 Move the test line for column formulas in the Org-mode buffer
1752 Scroll the window displaying the table.
1755 Turn the coordinate grid in the table on and off.
1757 Making a table field blank does not remove the formula associated
1758 with the field, because that is stored in a different line (the `TBLFM'
1759 line) - during the next recalculation the field will be filled again.
1760 To remove a formula from a field, you have to give an empty reply when
1761 prompted for the formula, or to edit the `#+TBLFM' line.
1763 You may edit the `#+TBLFM' directly and re-apply the changed
1764 equations with `C-c C-c' in that line, or with the normal recalculation
1765 commands in the table.
1770 When the evaluation of a formula leads to an error, the field content
1771 becomes the string `#ERROR'. If you would like see what is going on
1772 during variable substitution and calculation in order to find a bug,
1773 turn on formula debugging in the `Tbl' menu and repeat the calculation,
1774 for example by pressing `C-u C-u C-c = <RET>' in a field. Detailed
1775 information will be displayed.
1778 File: org, Node: Updating the table, Next: Advanced features, Prev: Editing and debugging formulas, Up: The spreadsheet
1780 3.5.7 Updating the Table
1781 ------------------------
1783 Recalculation of a table is normally not automatic, but needs to be
1784 triggered by a command. See *Note Advanced features:: for a way to make
1785 recalculation at least semi-automatically.
1787 In order to recalculate a line of a table or the entire table, use
1788 the following commands:
1791 Recalculate the current row by first applying the stored column
1792 formulas from left to right, and all field formulas in the current
1797 Recompute the entire table, line by line. Any lines before the
1798 first hline are left alone, assuming that these are part of the
1803 Iterate the table by recomputing it until no further changes occur.
1804 This may be necessary if some computed fields use the value of
1805 other fields that are computed later in the calculation sequence.
1808 File: org, Node: Advanced features, Prev: Updating the table, Up: The spreadsheet
1810 3.5.8 Advanced features
1811 -----------------------
1813 If you want the recalculation of fields to happen automatically, or if
1814 you want to be able to assign names to fields and columns, you need to
1815 reserve the first column of the table for special marking characters.
1817 Rotate the calculation mark in first column through the states `',
1818 `#', `*', `!', `$'. The meaning of these characters is discussed
1819 below. When there is an active region, change all marks in the
1822 Here is an example of a table that collects exam results of students
1823 and makes use of these features:
1825 |---+---------+--------+--------+--------+-------+------|
1826 | | Student | Prob 1 | Prob 2 | Prob 3 | Total | Note |
1827 |---+---------+--------+--------+--------+-------+------|
1828 | ! | | P1 | P2 | P3 | Tot | |
1829 | # | Maximum | 10 | 15 | 25 | 50 | 10.0 |
1830 | ^ | | m1 | m2 | m3 | mt | |
1831 |---+---------+--------+--------+--------+-------+------|
1832 | # | Peter | 10 | 8 | 23 | 41 | 8.2 |
1833 | # | Sara | 6 | 14 | 19 | 39 | 7.8 |
1834 | # | Sam | 2 | 4 | 3 | 9 | 1.8 |
1835 |---+---------+--------+--------+--------+-------+------|
1836 | | Average | | | | 29.7 | |
1837 | ^ | | | | | at | |
1838 | $ | max=50 | | | | | |
1839 |---+---------+--------+--------+--------+-------+------|
1840 #+TBLFM: $6=vsum($P1..$P3)::$7=10*$Tot/$max;%.1f::$at=vmean(@-II..@-I);%.1f
1842 Important: Please note that for these special tables, recalculating the
1843 table with `C-u C-c *' will only affect rows that are marked `#' or
1844 `*', and fields that have a formula assigned to the field itself. The
1845 column formulas are not applied in rows with empty first field.
1847 The marking characters have the following meaning:
1849 The fields in this line define names for the columns, so that you
1850 may refer to a column as `$Tot' instead of `$6'.
1853 This row defines names for the fields _above_ the row. With such
1854 a definition, any formula in the table may use `$m1' to refer to
1855 the value `10'. Also, if you assign a formula to a names field, it
1856 will be stored as `$name=...'.
1859 Similar to `^', but defines names for the fields in the row
1863 Fields in this row can define _parameters_ for formulas. For
1864 example, if a field in a `$' row contains `max=50', then formulas
1865 in this table can refer to the value 50 using `$max'. Parameters
1866 work exactly like constants, only that they can be defined on a
1870 Fields in this row are automatically recalculated when pressing
1871 <TAB> or <RET> or `S-<TAB>' in this row. Also, this row is
1872 selected for a global recalculation with `C-u C-c *'. Unmarked
1873 lines will be left alone by this command.
1876 Selects this line for global recalculation with `C-u C-c *', but
1877 not for automatic recalculation. Use this when automatic
1878 recalculation slows down editing too much.
1881 Unmarked lines are exempt from recalculation with `C-u C-c *'.
1882 All lines that should be recalculated should be marked with `#' or
1886 Do not export this line. Useful for lines that contain the
1887 narrowing `<N>' markers.
1889 Finally, just to whet your appetite on what can be done with the
1890 fantastic `calc' package, here is a table that computes the Taylor
1891 series of degree `n' at location `x' for a couple of functions
1892 (homework: try that with Excel :-)
1894 |---+-------------+---+-----+--------------------------------------|
1895 | | Func | n | x | Result |
1896 |---+-------------+---+-----+--------------------------------------|
1897 | # | exp(x) | 1 | x | 1 + x |
1898 | # | exp(x) | 2 | x | 1 + x + x^2 / 2 |
1899 | # | exp(x) | 3 | x | 1 + x + x^2 / 2 + x^3 / 6 |
1900 | # | x^2+sqrt(x) | 2 | x=0 | x*(0.5 / 0) + x^2 (2 - 0.25 / 0) / 2 |
1901 | # | x^2+sqrt(x) | 2 | x=1 | 2 + 2.5 x - 2.5 + 0.875 (x - 1)^2 |
1902 | * | tan(x) | 3 | x | 0.0175 x + 1.77e-6 x^3 |
1903 |---+-------------+---+-----+--------------------------------------|
1904 #+TBLFM: $5=taylor($2,$4,$3);n3
1907 File: org, Node: Hyperlinks, Next: TODO items, Prev: Tables, Up: Top
1912 Just like HTML, Org-mode provides links inside a file, and external
1913 links to other files, Usenet articles, emails, and much more.
1917 * Link format:: How links in Org-mode are formatted
1918 * Internal links:: Links to other places in the current file
1919 * External links:: URL-like links to the world
1920 * Handling links:: Creating, inserting and following
1921 * Using links outside Org-mode:: Linking from my C source code?
1922 * Link abbreviations:: Shortcuts for writing complex links
1923 * Search options:: Linking to a specific location
1924 * Custom searches:: When the default search is not enough
1927 File: org, Node: Link format, Next: Internal links, Prev: Hyperlinks, Up: Hyperlinks
1932 Org-mode will recognize plain URL-like links and activate them as
1933 clickable links. The general link format, however, looks like this:
1935 [[link][description]] or alternatively [[link]]
1937 Once a link in the buffer is complete (all brackets present),
1938 Org-mode will change the display so that `description' is displayed
1939 instead of `[[link][description]]' and `link' is displayed instead of
1940 `[[link]]'. Links will be highlighted in the face `org-link', which by
1941 default is an underlined face. You can directly edit the visible part
1942 of a link. Note that this can be either the `link' part (if there is
1943 no description) or the `description' part. To edit also the invisible
1944 `link' part, use `C-c C-l' with the cursor on the link.
1946 If you place the cursor at the beginning or just behind the end of
1947 the displayed text and press <BACKSPACE>, you will remove the
1948 (invisible) bracket at that location. This makes the link incomplete
1949 and the internals are again displayed as plain text. Inserting the
1950 missing bracket hides the link internals again. To show the internal
1951 structure of all links, use the menu entry `Org->Hyperlinks->Literal
1955 File: org, Node: Internal links, Next: External links, Prev: Link format, Up: Hyperlinks
1960 If the link does not look like a URL, it is considered to be internal in
1961 the current file. Links such as `[[My Target]]' or `[[My Target][Find
1962 my target]]' lead to a text search in the current file. The link can
1963 be followed with `C-c C-o' when the cursor is on the link, or with a
1964 mouse click (*note Handling links::). The preferred match for such a
1965 link is a dedicated target: the same string in double angular brackets.
1966 Targets may be located anywhere; sometimes it is convenient to put
1967 them into a comment line. For example
1971 In HTML export (*note HTML export::), such targets will become named
1972 anchors for direct access through `http' links(1).
1974 If no dedicated target exists, Org-mode will search for the words in
1975 the link. In the above example the search would be for `my target'.
1976 Links starting with a star like `*My Target' restrict the search to
1977 headlines. When searching, Org-mode will first try an exact match, but
1978 then move on to more and more lenient searches. For example, the link
1979 `[[*My Targets]]' will find any of the following:
1982 ** TODO my targets are bright
1983 ** my 20 targets are
1985 To insert a link targeting a headline, in-buffer completion can be
1986 used. Just type a star followed by a few optional letters into the
1987 buffer and press `M-<TAB>'. All headlines in the current buffer will be
1988 offered as completions. *Note Handling links::, for more commands
1991 Following a link pushes a mark onto Org-mode's own mark ring. You
1992 can return to the previous position with `C-c &'. Using this command
1993 several times in direct succession goes back to positions recorded
1998 * Radio targets:: Make targets trigger links in plain text.
2000 ---------- Footnotes ----------
2002 (1) Note that text before the first headline is usually not
2003 exported, so the first such target should be after the first headline.
2006 File: org, Node: Radio targets, Prev: Internal links, Up: Internal links
2011 Org-mode can automatically turn any occurrences of certain target names
2012 in normal text into a link. So without explicitly creating a link, the
2013 text connects to the target radioing its position. Radio targets are
2014 enclosed by triple angular brackets. For example, a target `<<<My
2015 Target>>>' causes each occurrence of `my target' in normal text to
2016 become activated as a link. The Org-mode file is scanned automatically
2017 for radio targets only when the file is first loaded into Emacs. To
2018 update the target list during editing, press `C-c C-c' with the cursor
2022 File: org, Node: External links, Next: Handling links, Prev: Internal links, Up: Hyperlinks
2027 Org-mode supports links to files, websites, Usenet and email messages,
2028 and BBDB database entries. External links are URL-like locators. They
2029 start with a short identifying string followed by a colon. There can be
2030 no space after the colon. The following list shows examples for each
2033 http://www.astro.uva.nl/~dominik on the web
2034 file:/home/dominik/images/jupiter.jpg file, absolute path
2035 file:papers/last.pdf file, relative path
2036 news:comp.emacs Usenet link
2037 mailto:adent@galaxy.net Mail link
2038 vm:folder VM folder link
2039 vm:folder#id VM message link
2040 vm://myself@some.where.org/folder#id VM on remote machine
2041 wl:folder WANDERLUST folder link
2042 wl:folder#id WANDERLUST message link
2043 mhe:folder MH-E folder link
2044 mhe:folder#id MH-E message link
2045 rmail:folder RMAIL folder link
2046 rmail:folder#id RMAIL message link
2047 gnus:group GNUS group link
2048 gnus:group#id GNUS article link
2049 bbdb:Richard Stallman BBDB link
2050 shell:ls *.org A shell command
2051 elisp:(find-file-other-frame "Elisp.org") An elisp form to evaluate
2053 A link should be enclosed in double brackets and may contain a
2054 descriptive text to be displayed instead of the url (*note Link
2055 format::), for example:
2057 [[http://www.gnu.org/software/emacs/][GNU Emacs]]
2059 If the description is a file name or URL that points to an image, HTML
2060 export (*note HTML export::) will inline the image as a clickable
2061 button. If there is no description at all and the link points to an
2062 image, that image will be inlined into the exported HTML file.
2064 Org-mode also finds external links in the normal text and activates
2065 them as links. If spaces must be part of the link (for example in
2066 `bbdb:Richard Stallman'), or if you need to remove ambiguities about
2067 the end of the link, enclose them in angular brackets.
2070 File: org, Node: Handling links, Next: Using links outside Org-mode, Prev: External links, Up: Hyperlinks
2075 Org-mode provides methods to create a link in the correct syntax, to
2076 insert it into an org-mode file, and to follow the link.
2079 Store a link to the current location. This is a _global_ command
2080 which can be used in any buffer to create a link. The link will be
2081 stored for later insertion into an Org-mode buffer (see below).
2082 For Org-mode files, if there is a `<<target>>' at the cursor, the
2083 link points to the target. Otherwise it points to the current
2084 headline. For VM, RMAIL, WANDERLUST, MH-E, GNUS and BBDB buffers,
2085 the link will indicate the current article/entry. For W3 and W3M
2086 buffers, the link goes to the current URL. For any other files,
2087 the link will point to the file, with a search string (*note
2088 Search options::) pointing to the contents of the current line.
2089 If there is an active region, the selected words will form the
2090 basis of the search string. If the automatically created link is
2091 not working correctly or accurately enough, you can write custom
2092 functions to select the search string and to do the search for
2093 particular file types - see *Note Custom searches::. The key
2094 binding `C-c l' is only a suggestion - see *Note Installation::.
2097 Insert a link. This prompts for a link to be inserted into the
2098 buffer. You can just type a link, using text for an internal
2099 link, or one of the link type prefixes mentioned in the examples
2100 above. All links stored during the current session are part of
2101 the history for this prompt, so you can access them with <up> and
2102 <down> (or `M-p/n'). Completion, on the other hand, will help you
2103 to insert valid link prefixes like `http:' or `ftp:', including
2104 the prefixes defined through link abbreviations (*note Link
2105 abbreviations::). The link will be inserted into the buffer(1),
2106 along with a descriptive text. If some text was selected when
2107 this command is called, the selected text becomes the default
2109 Note that you don't have to use this command to insert a link.
2110 Links in Org-mode are plain text, and you can type or paste them
2111 straight into the buffer. By using this command, the links are
2112 automatically enclosed in double brackets, and you will be asked
2113 for the optional descriptive text.
2116 When `C-c C-l' is called with a `C-u' prefix argument, a link to a
2117 file will be inserted and you may use file name completion to
2118 select the name of the file. The path to the file is inserted
2119 relative to the directory of the current org file, if the linked
2120 file is in the current directory or in a subdirectory of it, or if
2121 the path is written relative to the current directory using `../'.
2122 Otherwise an absolute path is used, if possible with `~/' for
2123 your home directory. You can force an absolute path with two
2126 `C-c C-l (with cursor on existing link)'
2127 When the cursor is on an existing link, `C-c C-l' allows you to
2128 edit the link and description parts of the link.
2131 Open link at point. This will launch a web browser for URLs (using
2132 `browse-url-at-point'), run vm/mh-e/wanderlust/rmail/gnus/bbdb for
2133 the corresponding links, and execute the command in a shell link.
2134 When the cursor is on an internal link, this commands runs the
2135 corresponding search. When the cursor is on a TAG list in a
2136 headline, it creates the corresponding TAGS view. If the cursor
2137 is on a time stamp, it compiles the agenda for that date.
2138 Furthermore, it will visit text and remote files in `file:' links
2139 with Emacs and select a suitable application for local non-text
2140 files. Classification of files is based on file extension only.
2141 See option `org-file-apps'. If you want to override the default
2142 application and visit the file with Emacs, use a `C-u' prefix.
2146 On links, `mouse-2' will open the link just as `C-c C-o' would.
2147 Under Emacs 22, also `mouse-1' will follow a link.
2150 Like `mouse-2', but force file links to be opened with Emacs, and
2151 internal links to be displayed in another window(2).
2154 Push the current position onto the mark ring, to be able to return
2155 easily. Commands following an internal link do this automatically.
2158 Jump back to a recorded position. A position is recorded by the
2159 commands following internal links, and by `C-c %'. Using this
2160 command several times in direct succession moves through a ring of
2161 previously recorded positions.
2165 Move forward/backward to the next link in the buffer. At the
2166 limit of the buffer, the search fails once, and then wraps around.
2167 The key bindings for this are really too long, you might want to
2168 bind this also to `C-n' and `C-p'
2169 (add-hook 'org-load-hook
2171 (define-key 'org-mode-map "\C-n" 'org-next-link)
2172 (define-key 'org-mode-map "\C-p" 'org-previous-link)))
2174 ---------- Footnotes ----------
2176 (1) After insertion of a stored link, the link will be removed from
2177 the list of stored links. To keep it in the list later use, use a
2178 triple `C-u' prefix to `C-c C-l', or configure the option
2179 `org-keep-stored-link-after-insertion'.
2181 (2) See the variable `org-display-internal-link-with-indirect-buffer'
2184 File: org, Node: Using links outside Org-mode, Next: Link abbreviations, Prev: Handling links, Up: Hyperlinks
2186 4.5 Using links outside Org-mode
2187 ================================
2189 You can insert and follow links that have Org-mode syntax not only in
2190 Org-mode, but in any Emacs buffer. For this, you should create two
2191 global commands, like this (please select suitable global keys
2194 (global-set-key "\C-c L" 'org-insert-link-global)
2195 (global-set-key "\C-c o" 'org-open-at-point-global)
2198 File: org, Node: Link abbreviations, Next: Search options, Prev: Using links outside Org-mode, Up: Hyperlinks
2200 4.6 Link abbreviations
2201 ======================
2203 Long URLs can be cumbersome to type, and often many similar links are
2204 needed in a document. For this you can use link abbreviations. An
2205 abbreviated link looks like this
2207 [[linkword:tag][description]]
2209 where the tag is optional. Such abbreviations are resolved according to
2210 the information in the variable `org-link-abbrev-alist' that relates
2211 the linkwords to replacement text. Here is an example:
2213 (setq org-link-abbrev-alist
2214 '(("bugzilla" . "http://10.1.2.9/bugzilla/show_bug.cgi?id=")
2215 ("google" . "http://www.google.com/search?q=")
2216 ("ads" . "http://adsabs.harvard.edu/cgi-bin/
2217 nph-abs_connect?author=%s&db_key=AST")))
2219 If the replacement text contains the string `%s', it will be
2220 replaced with the tag. Otherwise the tag will be appended to the string
2221 in order to create the link. You may also specify a function that will
2222 be called with the tag as the only argument to create the link.
2224 With the above setting, you could link to a specific bug with
2225 `[[bugzilla:129]]', search the web for `OrgMode' with
2226 `[[google:OrgMode]]' and find out what the Org-mode author is doing
2227 besides Emacs hacking with `[[ads:Dominik,C]]'.
2229 If you need special abbreviations just for a single Org-mode buffer,
2230 you can define them in the file with
2232 #+LINK: bugzilla http://10.1.2.9/bugzilla/show_bug.cgi?id=
2233 #+LINK: google http://www.google.com/search?q=%s
2235 In-buffer completion *note Completion:: can be used after `[' to
2236 complete link abbreviations.
2239 File: org, Node: Search options, Next: Custom searches, Prev: Link abbreviations, Up: Hyperlinks
2241 4.7 Search options in file links
2242 ================================
2244 File links can contain additional information to make Emacs jump to a
2245 particular location in the file when following a link. This can be a
2246 line number or a search option after a double(1) colon. For example,
2247 when the command `C-c l' creates a link (*note Handling links::) to a
2248 file, it encodes the words in the current line as a search string that
2249 can be used to find this line back later when following the link with
2252 Here is the syntax of the different ways to attach a search to a file
2253 link, together with an explanation:
2255 [[file:~/code/main.c::255]]
2256 [[file:~/xx.org::My Target]]
2257 [[file:~/xx.org::*My Target]]
2258 [[file:~/xx.org::/regexp/]]
2264 Search for a link target `<<My Target>>', or do a text search for
2265 `my target', similar to the search in internal links, see *Note
2266 Internal links::. In HTML export (*note HTML export::), such a
2267 file link will become an HTML reference to the corresponding named
2268 anchor in the linked file.
2271 In an Org-mode file, restrict search to headlines.
2274 Do a regular expression search for `regexp'. This uses the Emacs
2275 command `occur' to list all matches in a separate window. If the
2276 target file is in Org-mode, `org-occur' is used to create a sparse
2277 tree with the matches.
2279 As a degenerate case, a file link with an empty file name can be used
2280 to search the current file. For example, `[[file:::find me]]' does a
2281 search for `find me' in the current file, just as `[[find me]]' would.
2283 ---------- Footnotes ----------
2285 (1) For backward compatibility, line numbers can also follow a
2289 File: org, Node: Custom searches, Prev: Search options, Up: Hyperlinks
2294 The default mechanism for creating search strings and for doing the
2295 actual search related to a file link may not work correctly in all
2296 cases. For example, BibTeX database files have many entries like
2297 `year="1993"' which would not result in good search strings, because
2298 the only unique identification for a BibTeX entry is the citation key.
2300 If you come across such a problem, you can write custom functions to
2301 set the right search string for a particular file type, and to do the
2302 search for the string in the file. Using `add-hook', these functions
2303 need to be added to the hook variables
2304 `org-create-file-search-functions' and
2305 `org-execute-file-search-functions'. See the docstring for these
2306 variables for more information. Org-mode actually uses this mechanism
2307 for BibTeX database files, and you can use the corresponding code as an
2308 implementation example. Search for `BibTeX links' in the source file.
2311 File: org, Node: TODO items, Next: Tags, Prev: Hyperlinks, Up: Top
2316 Org-mode does not maintain TODO lists as a separate document. TODO
2317 items are an integral part of the notes file, because TODO items
2318 usually come up while taking notes! With Org-mode, you simply mark any
2319 entry in a tree as being a TODO item. In this way, the information is
2320 not duplicated, and the entire context from which the item emerged is
2321 always present when you check.
2323 Of course, this technique causes TODO items to be scattered
2324 throughout your file. Org-mode provides methods to give you an
2325 overview over all things you have to do.
2329 * TODO basics:: Marking and displaying TODO entries
2330 * TODO extensions:: Workflow and assignments
2331 * Progress logging:: Dates and notes for progress
2332 * Priorities:: Some things are more important than others
2333 * Breaking down tasks:: Splitting a task into manageable pieces
2334 * Checkboxes:: Tick-off lists
2337 File: org, Node: TODO basics, Next: TODO extensions, Prev: TODO items, Up: TODO items
2339 5.1 Basic TODO functionality
2340 ============================
2342 Any headline can become a TODO item by starting it with the word TODO,
2345 *** TODO Write letter to Sam Fortune
2347 The most important commands to work with TODO entries are:
2350 Rotate the TODO state of the current item among
2352 ,-> (unmarked) -> TODO -> DONE --.
2353 '--------------------------------'
2355 The same rotation can also be done "remotely" from the timeline and
2356 agenda buffers with the `t' command key (*note Agenda commands::).
2359 Select a specific keyword using completion of (if it has been set
2360 up) the fast selection interface.
2364 Select the following/preceding TODO state, similar to cycling.
2365 Mostly useful if more than two TODO states are possible (*note
2369 Use the fast tag interface to quickly and directly select a
2370 specific TODO state. For this you need to assign keys to TODO
2372 #+SEQ_TODO: TODO(t) STARTED(s) WAITING(w) | DONE(d)
2373 See *Note Per file keywords:: and *Note Setting tags:: for more
2378 View TODO items in a _sparse tree_ (*note Sparse trees::). Folds
2379 the entire buffer, but shows all TODO items and the headings
2380 hierarchy above them. With prefix arg, search for a specific
2381 TODO. You will be prompted for the keyword, and you can also give
2382 a list of keywords like `kwd1|kwd2|...'. With numerical prefix N,
2383 show the tree for the Nth keyword in the variable
2384 `org-todo-keywords'. With two prefix args, find all TODO and DONE
2388 Show the global TODO list. This collects the TODO items from all
2389 agenda files (*note Agenda views::) into a single buffer. The
2390 buffer is in `agenda-mode', so there are commands to examine and
2391 manipulate the TODO entries directly from that buffer (*note
2392 Agenda commands::). *Note Global TODO list::, for more
2396 Insert a new TODO entry below the current one.
2399 File: org, Node: TODO extensions, Next: Progress logging, Prev: TODO basics, Up: TODO items
2401 5.2 Extended use of TODO keywords
2402 =================================
2404 The default implementation of TODO entries is just two states: TODO and
2405 DONE. You can use the TODO feature for more complicated things by
2406 configuring the variable `org-todo-keywords'. With special setup, the
2407 TODO keyword system can work differently in different files.
2409 Note that tags are another way to classify headlines in general and
2410 TODO items in particular (*note Tags::).
2414 * Workflow states:: From TODO to DONE in steps
2415 * TODO types:: I do this, Fred the rest
2416 * Multiple sets in one file:: Mixing it all, and still finding your way
2417 * Fast access to TODO states:: Single letter selection of a state
2418 * Per file keywords:: Different files, different requirements
2419 * Faces for TODO keywords:: Highlighting states
2422 File: org, Node: Workflow states, Next: TODO types, Prev: TODO extensions, Up: TODO extensions
2424 5.2.1 TODO keywords as workflow states
2425 --------------------------------------
2427 You can use TODO keywords to indicate different _sequential_ states in
2428 the process of working on an item, for example(1):
2430 (setq org-todo-keywords
2431 '((sequence "TODO" "FEEDBACK" "VERIFY" "|" "DONE" "DELEGATED")))
2433 The vertical bar separates the TODO keywords (states that _need
2434 action_) from the DONE states (which need _no further action_. If you
2435 don't provide the separator bar, the last state is used as the DONE
2436 state. With this setup, the command `C-c C-t' will cycle an entry from
2437 TODO to FEEDBACK, then to VERIFY, and finally to DONE and DELEGATED.
2438 You may also use a prefix argument to quickly select a specific state.
2439 For example `C-3 C-c C-t' will change the state immediately to VERIFY.
2440 If you define many keywords, you can use in-buffer completion (see
2441 *Note Completion::) to insert these words into the buffer. Changing a
2442 todo state can be logged with a timestamp, see *Note Tracking TODO
2443 state changes:: for more information.
2445 ---------- Footnotes ----------
2447 (1) Changing this variable only becomes effective after restarting
2448 Org-mode in a buffer.
2451 File: org, Node: TODO types, Next: Multiple sets in one file, Prev: Workflow states, Up: TODO extensions
2453 5.2.2 TODO keywords as types
2454 ----------------------------
2456 The second possibility is to use TODO keywords to indicate different
2457 _types_ of action items. For example, you might want to indicate that
2458 items are for "work" or "home". Or, when you work with several people
2459 on a single project, you might want to assign action items directly to
2460 persons, by using their names as TODO keywords. This would be set up
2463 (setq org-todo-keywords '((type "Fred" "Sara" "Lucy" "|" "DONE")))
2465 In this case, different keywords do not indicate a sequence, but
2466 rather different types. So the normal work flow would be to assign a
2467 task to a person, and later to mark it DONE. Org-mode supports this
2468 style by adapting the workings of the command `C-c C-t'(1). When used
2469 several times in succession, it will still cycle through all names, in
2470 order to first select the right type for a task. But when you return
2471 to the item after some time and execute `C-c C-t' again, it will switch
2472 from any name directly to DONE. Use prefix arguments or completion to
2473 quickly select a specific name. You can also review the items of a
2474 specific TODO type in a sparse tree by using a numeric prefix to `C-c
2475 C-v'. For example, to see all things Lucy has to do, you would use
2476 `C-3 C-c C-v'. To collect Lucy's items from all agenda files into a
2477 single buffer, you would use the prefix arg as well when creating the
2478 global todo list: `C-3 C-c t'.
2480 ---------- Footnotes ----------
2482 (1) This is also true for the `t' command in the timeline and agenda
2486 File: org, Node: Multiple sets in one file, Next: Fast access to TODO states, Prev: TODO types, Up: TODO extensions
2488 5.2.3 Multiple keyword sets in one file
2489 ---------------------------------------
2491 Sometimes you may want to use different sets of TODO keywords in
2492 parallel. For example, you may want to have the basic `TODO'/`DONE',
2493 but also a workflow for bug fixing, and a separate state indicating
2494 that an item has been canceled (so it is not DONE, but also does not
2495 require action). Your setup would then look like this:
2497 (setq org-todo-keywords
2498 '((sequence "TODO" "|" "DONE")
2499 (sequence "REPORT" "BUG" "KNOWNCAUSE" "|" "FIXED")
2500 (sequence "|" "CANCELED")))
2502 The keywords should all be different, this helps Org-mode to keep
2503 track of which subsequence should be used for a given entry. In this
2504 setup, `C-c C-t' only operates within a subsequence, so it switches from
2505 `DONE' to (nothing) to `TODO', and from `FIXED' to (nothing) to
2506 `REPORT'. Therefore you need a mechanism to initially select the
2507 correct sequence. Besides the obvious ways like typing a keyword or
2508 using completion, you may also apply the following commands:
2512 These keys jump from one TODO subset to the next. In the above
2513 example, `C-S-<right>' would jump from `TODO' or `DONE' to
2514 `REPORT', and any of the words in the second row to `CANCELED'.
2518 `S-<<left>>' and `S-<<right>>' and walk through _all_ keywords
2519 from all sets, so for example `S-<<right>>' would switch from
2520 `DONE' to `REPORT' in the example above.
2523 File: org, Node: Fast access to TODO states, Next: Per file keywords, Prev: Multiple sets in one file, Up: TODO extensions
2525 5.2.4 Fast access to TODO states
2526 --------------------------------
2528 If you would like to quickly change an entry to an arbitrary TODO state
2529 instead of cycling through the states, you can set up keys for
2530 single-letter access to the states. This is done by adding the section
2531 key after each keyword, in parenthesis. For example:
2533 (setq org-todo-keywords
2534 '((sequence "TODO(t)" "|" "DONE(d)")
2535 (sequence "REPORT(r)" "BUG(b)" "KNOWNCAUSE(k)" "|" "FIXED(f)")
2536 (sequence "|" "CANCELED(c)")))
2538 If you then press `C-u C-c C-t' followed by the selection key, the
2539 entry will be switched to this state. <SPC> can be used to remove any
2540 TODO keyword from an entry. Should you like this way of selecting TODO
2541 states a lot, you might want to set the variable
2542 `org-use-fast-todo-selection' to `t' and make this behavior the
2543 default. Check also the variable
2544 `org-fast-tag-selection-include-todo', it allows to change the TODO
2545 state through the tags interface (*note Setting tags::).
2548 File: org, Node: Per file keywords, Next: Faces for TODO keywords, Prev: Fast access to TODO states, Up: TODO extensions
2550 5.2.5 Setting up keywords for individual files
2551 ----------------------------------------------
2553 It can be very useful to use different aspects of the TODO mechanism in
2554 different files. For file-local settings, you need to add special lines
2555 to the file which set the keywords and interpretation for that file
2556 only. For example, to set one of the two examples discussed above, you
2557 need one of the following lines, starting in column zero anywhere in the
2560 #+SEQ_TODO: TODO FEEDBACK VERIFY | DONE CANCELED
2562 #+TYP_TODO: Fred Sara Lucy Mike | DONE
2564 A setup for using several sets in parallel would be:
2566 #+SEQ_TODO: TODO | DONE
2567 #+SEQ_TODO: REPORT BUG KNOWNCAUSE | FIXED
2568 #+SEQ_TODO: | CANCELED
2570 To make sure you are using the correct keyword, type `#+' into the
2571 buffer and then use `M-<TAB>' completion.
2573 Remember that the keywords after the vertical bar (or the last
2574 keyword if no bar is there) must always mean that the item is DONE
2575 (although you may use a different word). After changing one of these
2576 lines, use `C-c C-c' with the cursor still in the line to make the
2577 changes known to Org-mode(1).
2579 ---------- Footnotes ----------
2581 (1) Org-mode parses these lines only when Org-mode is activated
2582 after visiting a file. `C-c C-c' with the cursor in a line starting
2583 with `#+' is simply restarting Org-mode for the current buffer.
2586 File: org, Node: Faces for TODO keywords, Prev: Per file keywords, Up: TODO extensions
2588 5.2.6 Faces for TODO keywords
2589 -----------------------------
2591 Org-mode highlights TODO keywords with special faces: `org-todo' for
2592 keywords indicating that an item still has to be acted upon, and
2593 `org-done' for keywords indicating that an item is finished. If you
2594 are using more than 2 different states, you might want to use special
2595 faces for some of them. This can be done using the variable
2596 `org-todo-keyword-faces'. For example:
2598 (setq org-todo-keyword-faces
2599 '(("TODO" . org-warning)
2600 ("DEFERRED" . shadow)
2601 ("CANCELED" . (:foreground "blue" :weight bold))))
2604 File: org, Node: Progress logging, Next: Priorities, Prev: TODO extensions, Up: TODO items
2606 5.3 Progress Logging
2607 ====================
2609 Org-mode can automatically record a time stamp and even a note when you
2610 mark a TODO item as DONE, or even each time you change the state of a
2615 * Closing items:: When was this entry marked DONE?
2616 * Tracking TODO state changes:: When did the status change?
2619 File: org, Node: Closing items, Next: Tracking TODO state changes, Prev: Progress logging, Up: Progress logging
2624 If you want to keep track of _when_ a certain TODO item was finished,
2625 turn on logging with(1)
2627 (setq org-log-done t)
2629 Then each time you turn a TODO entry into DONE using either `C-c C-t'
2630 in the Org-mode buffer or `t' in the agenda buffer, a line `CLOSED:
2631 [timestamp]' will be inserted just after the headline. If you turn the
2632 entry back into a TODO item through further state cycling, that line
2633 will be removed again. In the timeline (*note Timeline::) and in the
2634 agenda (*note Weekly/Daily agenda::), you can then use the `l' key to
2635 display the TODO items closed on each day, giving you an overview of
2636 what has been done on a day. If you want to record a note along with
2637 the timestamp, use(2)
2639 (setq org-log-done '(done))
2641 ---------- Footnotes ----------
2643 (1) The corresponding in-buffer setting is: `#+STARTUP: logdone'.
2644 You may also set this for the scope of a subtree by adding a `LOGGING'
2645 property with one or more of the logging keywords in the value.
2647 (2) The corresponding in-buffer setting is: `#+STARTUP: lognotedone'
2650 File: org, Node: Tracking TODO state changes, Prev: Closing items, Up: Progress logging
2652 5.3.2 Tracking TODO state changes
2653 ---------------------------------
2655 When TODO keywords are used as workflow states (*note Workflow
2656 states::), you might want to keep track of when a state change occurred
2657 and record a note about this change. With the setting(1)
2659 (setq org-log-done '(state))
2661 each state change will prompt you for a note that will be attached to
2662 the current headline. If you press `C-c C-c' without typing anything
2663 into the note buffer, only the time of the state change will be noted.
2664 Very likely you do not want this verbose tracking all the time, so it
2665 is probably better to configure this behavior with in-buffer options.
2666 For example, if you are tracking purchases, put these into a separate
2669 #+SEQ_TODO: TODO(t) ORDERED(o) INVOICE(i) PAYED(p) | RECEIVED(r)
2670 #+STARTUP: lognotestate
2672 If you only need to take a note for some of the states, mark those
2673 states with an additional `@', like this:
2675 #+SEQ_TODO: TODO(t) ORDERED(o@) INVOICE(i@) PAYED(p) | RECEIVED(r)
2676 #+STARTUP: lognotestate
2678 ---------- Footnotes ----------
2680 (1) The corresponding in-buffer setting is: `#+STARTUP:
2684 File: org, Node: Priorities, Next: Breaking down tasks, Prev: Progress logging, Up: TODO items
2689 If you use Org-mode extensively to organize your work, you may end up
2690 with a number of TODO entries so large that you'd like to prioritize
2691 them. This can be done by placing a _priority cookie_ into the
2694 *** TODO [#A] Write letter to Sam Fortune
2696 With its standard setup, Org-mode supports priorities `A', `B', and
2697 `C'. `A' is the highest priority. An entry without a cookie is
2698 treated as priority `B'. Priorities make a difference only in the
2699 agenda (*note Weekly/Daily agenda::).
2702 Set the priority of the current headline. The command prompts for
2703 a priority character `A', `B' or `C'. When you press <SPC>
2704 instead, the priority cookie is removed from the headline. The
2705 priorities can also be changed "remotely" from the timeline and
2706 agenda buffer with the `,' command (*note Agenda commands::).
2710 Increase/decrease priority of current headline(1). Note that these
2711 keys are also used to modify time stamps (*note Creating
2712 timestamps::). Furthermore, these keys are also used by CUA-mode
2713 (*note Conflicts::).
2715 You can change the range of allowed priorities by setting the
2716 variables `org-highest-priority', `org-lowest-priority', and
2717 `org-default-priority'. For an individual buffer, you may set these
2718 values (highest, lowest, default) like this (please make sure that the
2719 highest priority is earlier in the alphabet than the lowest priority):
2723 ---------- Footnotes ----------
2725 (1) See also the option `org-priority-start-cycle-with-default''.
2728 File: org, Node: Breaking down tasks, Next: Checkboxes, Prev: Priorities, Up: TODO items
2730 5.5 Breaking tasks down into subtasks
2731 =====================================
2733 It is often advisable to break down large tasks into smaller, manageable
2734 subtasks. You can do this by creating an outline tree below a TODO
2735 item, with detailed subtasks on the tree(1). Another possibility is
2736 the use of checkboxes to identify (a hierarchy of) a large number of
2737 subtasks (*note Checkboxes::).
2739 ---------- Footnotes ----------
2741 (1) To keep subtasks out of the global TODO list, see the
2742 `org-agenda-todo-list-sublevels'.
2745 File: org, Node: Checkboxes, Prev: Breaking down tasks, Up: TODO items
2750 Every item in a plain list (*note Plain lists::) can be made a checkbox
2751 by starting it with the string `[ ]'. This feature is similar to TODO
2752 items (*note TODO items::), but more lightweight. Checkboxes are not
2753 included into the global TODO list, so they are often great to split a
2754 task into a number of simple steps. Or you can use them in a shopping
2755 list. To toggle a checkbox, use `C-c C-c', or try Piotr Zielinski's
2756 `org-mouse.el'. Here is an example of a checkbox list.
2758 * TODO Organize party [3/6]
2764 - [ ] think about what music to play
2765 - [X] talk to the neighbors
2767 The `[3/6]' and `[1/3]' in the first and second line are cookies
2768 indicating how many checkboxes are present in this entry, and how many
2769 of them have been checked off. This can give you an idea on how many
2770 checkboxes remain, even without opening a folded entry. The cookies
2771 can be placed into a headline or into (the first line of) a plain list
2772 item. Each cookie covers all checkboxes structurally below that
2773 headline/item. You have to insert the cookie yourself by typing either
2774 `[/]' or `[%]'. In the first case you get an `n out of m' result, in
2775 the second case you get information about the percentage of checkboxes
2776 checked (in the above example, this would be `[50%]' and `[33%],
2779 The following commands work with checkboxes:
2782 Toggle checkbox at point. With prefix argument, set it to `[-]',
2783 which is considered to be an intermediate state.
2786 Toggle checkbox at point.
2787 - If there is an active region, toggle the first checkbox in
2788 the region and set all remaining boxes to the same status as
2789 the first. If you want to toggle all boxes in the region
2790 independently, use a prefix argument.
2792 - If the cursor is in a headline, toggle checkboxes in the
2793 region between this headline and the next (so _not_ the
2796 - If there is no active region, just toggle the checkbox at
2800 Insert a new item with a checkbox. This works only if the cursor
2801 is already in a plain list item (*note Plain lists::).
2804 Update the checkbox statistics in the current outline entry. When
2805 called with a `C-u' prefix, update the entire file. Checkbox
2806 statistic cookies are updated automatically if you toggle
2807 checkboxes with `C-c C-c' and make new ones with `M-S-<RET>'. If
2808 you delete boxes or add/change them by hand, use this command to
2809 get things back into synch. Or simply toggle any checkbox twice
2813 File: org, Node: Tags, Next: Properties and columns, Prev: TODO items, Up: Top
2818 If you wish to implement a system of labels and contexts for
2819 cross-correlating information, an excellent way is to assign tags to
2820 headlines. Org-mode has extensive support for using tags.
2822 Every headline can contain a list of tags, at the end of the
2823 headline. Tags are normal words containing letters, numbers, `_', and
2824 `@'. Tags must be preceded and followed by a single colon; like
2825 `:WORK:'. Several tags can be specified like `:WORK:URGENT:'.
2829 * Tag inheritance:: Tags use the tree structure of the outline
2830 * Setting tags:: How to assign tags to a headline
2831 * Tag searches:: Searching for combinations of tags
2834 File: org, Node: Tag inheritance, Next: Setting tags, Prev: Tags, Up: Tags
2839 Tags make use of the hierarchical structure of outline trees. If a
2840 heading has a certain tag, all subheadings will inherit the tag as
2841 well. For example, in the list
2843 * Meeting with the French group :WORK:
2844 ** Summary by Frank :BOSS:NOTES:
2845 *** TODO Prepare slides for him :ACTION:
2847 the final heading will have the tags `:WORK:', `:BOSS:', `:NOTES:', and
2848 `:ACTION:'. When executing tag searches and Org-mode finds that a
2849 certain headline matches the search criterion, it will not check any
2850 sublevel headline, assuming that these likely also match, and that the
2851 list of matches can become very long. This may not be what you want,
2852 however, and you can influence inheritance and searching using the
2853 variables `org-use-tag-inheritance' and `org-tags-match-list-sublevels'.
2856 File: org, Node: Setting tags, Next: Tag searches, Prev: Tag inheritance, Up: Tags
2861 Tags can simply be typed into the buffer at the end of a headline.
2862 After a colon, `M-<TAB>' offers completion on tags. There is also a
2863 special command for inserting tags:
2866 Enter new tags for the current headline. Org-mode will either
2867 offer completion or a special single-key interface for setting
2868 tags, see below. After pressing <RET>, the tags will be inserted
2869 and aligned to `org-tags-column'. When called with a `C-u'
2870 prefix, all tags in the current buffer will be aligned to that
2871 column, just to make things look nice. TAGS are automatically
2872 realigned after promotion, demotion, and TODO state changes (*note
2875 Org will support tag insertion based on a _list of tags_. By
2876 default this list is constructed dynamically, containing all tags
2877 currently used in the buffer. You may also globally specify a hard list
2878 of tags with the variable `org-tag-alist'. Finally you can set the
2879 default tags for a given file with lines like
2881 #+TAGS: @WORK @HOME @TENNISCLUB
2882 #+TAGS: Laptop Car PC Sailboat
2884 If you have globally defined your preferred set of tags using the
2885 variable `org-tag-alist', but would like to use a dynamic tag list in a
2886 specific file: Just add an empty TAGS option line to that file:
2890 The default support method for entering tags is minibuffer
2891 completion. However, Org-mode also implements a much better method:
2892 _fast tag selection_. This method allows to select and deselect tags
2893 with a single key per tag. To function efficiently, you should assign
2894 unique keys to most tags. This can be done globally with
2896 (setq org-tag-alist '(("@WORK" . ?w) ("@HOME" . ?h) ("Laptop" . ?l)))
2898 or on a per-file basis with
2900 #+TAGS: @WORK(w) @HOME(h) @TENNISCLUB(t) Laptop(l) PC(p)
2902 You can also group together tags that are mutually exclusive. With
2905 #+TAGS: { @WORK(w) @HOME(h) @TENNISCLUB(t) } Laptop(l) PC(p)
2907 you indicate that at most one of `@WORK', `@HOME', and `@TENNISCLUB'
2910 Don't forget to press `C-c C-c' with the cursor in one of these lines
2911 to activate any changes.
2913 If at least one tag has a selection key, pressing `C-c C-c' will
2914 automatically present you with a special interface, listing inherited
2915 tags, the tags of the current headline, and a list of all legal tags
2916 with corresponding keys(2). In this interface, you can use the
2920 Pressing keys assigned to tags will add or remove them from the
2921 list of tags in the current line. Selecting a tag in a group of
2922 mutually exclusive tags will turn off any other tags from that
2926 Enter a tag in the minibuffer, even if the tag is not in the
2927 predefined list. You will be able to complete on all tags present
2931 Clear all tags for this line.
2934 Accept the modified set.
2937 Abort without installing changes.
2940 If `q' is not assigned to a tag, it aborts like `C-g'.
2943 Turn off groups of mutually exclusive tags. Use this to (as an
2944 exception) assign several tags from such a group.
2947 Toggle auto-exit after the next change (see below). If you are
2948 using expert mode, the first `C-c' will display the selection
2951 This method lets you assign tags to a headline with very few keys. With
2952 the above setup, you could clear the current tags and set `@HOME',
2953 `Laptop' and `PC' tags with just the following keys: `C-c C-c <SPC> h l
2954 p <RET>'. Switching from `@HOME' to `@WORK' would be done with `C-c
2955 C-c w <RET>' or alternatively with `C-c C-c C-c w'. Adding the
2956 non-predefined tag `Sarah' could be done with `C-c C-c <TAB> S a r a h
2959 If you find that most of the time, you need only a single keypress to
2960 modify your list of tags, set the variable
2961 `org-fast-tag-selection-single-key'. Then you no longer have to press
2962 <RET> to exit fast tag selection - it will immediately exit after the
2963 first change. If you then occasionally need more keys, press `C-c' to
2964 turn off auto-exit for the current tag selection process (in effect:
2965 start selection with `C-c C-c C-c' instead of `C-c C-c'). If you set
2966 the variable to the value `expert', the special window is not even
2967 shown for single-key tag selection, it comes up only when you press an
2970 ---------- Footnotes ----------
2972 (1) In `org-mode-alist' use `'(:startgroup)' and `'(:endgroup)',
2973 respectively. Several groups are allowed.
2975 (2) Keys will automatically be assigned to tags which have no
2979 File: org, Node: Tag searches, Prev: Setting tags, Up: Tags
2984 Once a tags system has been set up, it can be used to collect related
2985 information into special lists.
2989 Create a sparse tree with all headlines matching a tags search.
2990 With a `C-u' prefix argument, ignore headlines that are not a TODO
2994 Create a global list of tag matches from all agenda files. *Note
2995 Matching tags and properties::.
2998 Create a global list of tag matches from all agenda files, but
2999 check only TODO items and force checking subitems (see variable
3000 `org-tags-match-list-sublevels').
3002 A tags search string can use Boolean operators `&' for AND and `|'
3003 for OR. `&' binds more strongly than `|'. Parenthesis are currently
3004 not implemented. A tag may also be preceded by `-', to select against
3005 it, and `+' is syntactic sugar for positive selection. The AND
3006 operator `&' is optional when `+' or `-' is present. Examples:
3009 Select headlines tagged `:WORK:', but discard those also tagged
3013 Selects lines tagged `:WORK:' or `:LAPTOP:'.
3016 Like before, but require the `:LAPTOP:' lines to be tagged also
3019 If you are using multi-state TODO keywords (*note TODO
3020 extensions::), it can be useful to also match on the TODO keyword.
3021 This can be done by adding a condition after a slash to a tags match.
3022 The syntax is similar to the tag matches, but should be applied with
3023 consideration: For example, a positive selection on several TODO
3024 keywords can not meaningfully be combined with boolean AND. However,
3025 _negative selection_ combined with AND can be meaningful. To make sure
3026 that only lines are checked that actually have any TODO keyword, use
3027 `C-c a M', or equivalently start the todo part after the slash with `!'.
3031 Select `:WORK:'-tagged TODO lines with the specific TODO keyword
3034 `WORK/!-WAITING-NEXT'
3035 Select `:WORK:'-tagged TODO lines that are neither `WAITING' nor
3038 `WORK/+WAITING|+NEXT'
3039 Select `:WORK:'-tagged TODO lines that are either `WAITING' or
3042 Any element of the tag/todo match can be a regular expression - in
3043 this case it must be enclosed in curly braces. For example,
3044 `WORK+{^BOSS.*}' matches headlines that contain the tag `WORK' and any
3045 tag starting with `BOSS'.
3047 You can also require a headline to be of a certain level, by writing
3048 instead of any TAG an expression like `LEVEL=3'. For example, a search
3049 `+LEVEL=3+BOSS/-DONE' lists all level three headlines that have the tag
3050 BOSS and are _not_ marked with the todo keyword DONE.
3053 File: org, Node: Properties and columns, Next: Timestamps, Prev: Tags, Up: Top
3055 7 Properties and Columns
3056 ************************
3058 Properties are a set of key-value pairs associated with an entry. There
3059 are two main applications for properties in Org-mode. First, properties
3060 are like tags, but with a value. For example, in a file where you
3061 document bugs and plan releases of a piece of software, instead of using
3062 tags like `:release_1:', `:release_2:', it can be more efficient to use
3063 a property `RELEASE' with a value `1.0' or `2.0'. Second, you can use
3064 properties to implement (very basic) database capabilities in an
3065 Org-mode buffer, for example to create a list of Music CD's you own.
3066 You can edit and view properties conveniently in column view (*note
3071 * Property syntax:: How properties are spelled out
3072 * Special properties:: Access to other Org-mode features
3073 * Property searches:: Matching property values
3074 * Column view:: Tabular viewing and editing
3075 * Property API:: Properties for Lisp programmers
3078 File: org, Node: Property syntax, Next: Special properties, Prev: Properties and columns, Up: Properties and columns
3083 Properties are key-value pairs. They need to be inserted into a special
3084 drawer (*note Drawers::) with the name `PROPERTIES'. Each property is
3085 specified on a single line, with the key (surrounded by colons) first,
3086 and the value after it. Here is an example:
3090 *** Goldberg Variations
3092 :Title: Goldberg Variations
3093 :Composer: J.S. Bach
3095 :Publisher: Deutsche Grammphon
3099 You may define the allowed values for a particular property `XYZ' by
3100 setting a property `XYZ_ALL'. This special property is _inherited_, so
3101 if you set it in a level 1 entry, it will apply to the entire tree.
3102 When allowed values are defined, setting the corresponding property
3103 becomes easier and is less prone to typing errors. For the example
3104 with the CD collection, we can predefine publishers and the number of
3105 disks in a box like this:
3109 :NDisks_ALL: 1 2 3 4
3110 :Publisher_ALL: "Deutsche Grammophon" Phillips EMI
3113 If you want to set properties that can be inherited by any entry in a
3114 file, use a line like
3116 #+PROPERTY: NDisks_ALL 1 2 3 4
3118 Property values set with the global variable `org-global-properties'
3119 can be inherited by all entries in all Org-mode files.
3121 The following commands help to work with properties:
3124 After an initial colon in a line, complete property keys. All
3125 keys used in the current file will be offered as possible
3129 Set a property. This prompts for a property name and a value. If
3130 necessary, the property drawer is created as well.
3132 `M-x org-insert-property-drawer'
3133 Insert a property drawer into the current entry. The drawer will
3134 be inserted early in the entry, but after the lines with planning
3135 information like deadlines.
3138 With the cursor in a property drawer, this executes property
3142 Set a property in the current entry. Both the property and the
3143 value can be inserted using completion.
3146 Switch property at point to the next/previous allowed value.
3149 Remove a property from the current entry.
3152 Globally remove a property, from all entries in the current file.
3155 Compute the property at point, using the operator and scope from
3156 the nearest column format definition.
3159 File: org, Node: Special properties, Next: Property searches, Prev: Property syntax, Up: Properties and columns
3161 7.2 Special Properties
3162 ======================
3164 Special properties provide alternative access method to Org-mode
3165 features discussed in the previous chapters, like the TODO state or the
3166 priority of an entry. This interface exists so that you can include
3167 these states into columns view (*note Column view::). The following
3168 property names are special and should not be used as keys in the
3171 TODO The TODO keyword of the entry.
3172 TAGS The tags defined directly in the headline.
3173 ALLTAGS All tags, including inherited ones.
3174 PRIORITY The priority of the entry, a string with a single letter.
3175 DEADLINE The deadline time string, without the angular brackets.
3176 SCHEDULED The scheduling time stamp, without the angular brackets.
3179 File: org, Node: Property searches, Next: Column view, Prev: Special properties, Up: Properties and columns
3181 7.3 Property searches
3182 =====================
3184 To create sparse trees and special lists with selection based on
3185 properties, the same commands are used as for tag searches (*note Tag
3186 searches::), and the same logic applies. For example, a search string
3188 +WORK-BOSS+PRIORITY="A"+coffee="unlimited"+with={Sarah\|Denny}
3190 finds entries tagged `:WORK:' but not `:BOSS:', which also have a
3191 priority value `A', a `:coffee:' property with the value `unlimited',
3192 and a `:with:' property that is matched by the regular expression
3195 During a search, properties will be inherited from parent entries
3196 only if you configure the variable `org-use-property-inheritance'.
3198 There is also a special command for creating sparse trees based on a
3202 Create a sparse tree based on the value of a property. This first
3203 prompts for the name of a property, and then for a value. A
3204 sparse tree is created with all entries that define this property
3205 with the given value. If you enclose the value into curly braces,
3206 it is interpreted as a regular expression and matched against the
3210 File: org, Node: Column view, Next: Property API, Prev: Property searches, Up: Properties and columns
3215 A great way to view and edit properties in an outline tree is _column
3216 view_. In column view, each outline item is turned into a table row.
3217 Columns in this table provide access to properties of the entries.
3218 Org-mode implements columns by overlaying a tabular structure over the
3219 headline of each item. While the headlines have been turned into a
3220 table row, you can still change the visibility of the outline tree.
3221 For example, you get a compact table by switching to CONTENTS view
3222 (`S-<TAB> S-<TAB>', or simply `c' while column view is active), but you
3223 can still open, read, and edit the entry below each headline. Or, you
3224 can switch to column view after executing a sparse tree command and in
3225 this way get a table only for the selected items. Column view also
3226 works in agenda buffers (*note Agenda views::) where queries have
3227 collected selected items, possibly from a number of files.
3231 * Defining columns:: The COLUMNS format property
3232 * Using column view:: How to create and use column view
3235 File: org, Node: Defining columns, Next: Using column view, Prev: Column view, Up: Column view
3237 7.4.1 Defining Columns
3238 ----------------------
3240 Setting up a column view first requires defining the columns. This is
3241 done by defining a column format line.
3245 * Scope of column definitions:: Where defined, where valid?
3246 * Column attributes:: Appearance and content of a column
3249 File: org, Node: Scope of column definitions, Next: Column attributes, Prev: Defining columns, Up: Defining columns
3251 7.4.1.1 Scope of column definitions
3252 ...................................
3254 To define a column format for an entire file, use a line like
3256 #+COLUMNS: %25ITEM %TAGS %PRIORITY %TODO
3258 To specify a format that only applies to a specific tree, add a
3259 COLUMNS property to the top node of that tree, for example
3260 ** Top node for columns view
3262 :COLUMNS: %25ITEM %TAGS %PRIORITY %TODO
3265 If a `COLUMNS' property is present in an entry, it defines columns
3266 for the entry itself, and for the entire subtree below it. Since the
3267 column definition is part of the hierarchical structure of the document,
3268 you can define columns on level 1 that are general enough for all
3269 sublevels, and more specific columns further down, when you edit a
3270 deeper part of the tree.
3273 File: org, Node: Column attributes, Prev: Scope of column definitions, Up: Defining columns
3275 7.4.1.2 Column attributes
3276 .........................
3278 A column definition sets the attributes of a column. The general
3279 definition looks like this:
3281 %[width]property[(title)][{summary-type}]
3283 Except for the percent sign and the property name, all items are
3284 optional. The individual parts have the following meaning:
3286 width An integer specifying the width of the column in characters.
3287 If omitted, the width will be determined automatically.
3288 property The property that should be edited in this column.
3289 (title) The header text for the column. If omitted, the
3290 property name is used.
3291 {summary-type} The summary type. If specified, the column values for
3292 parent nodes are computed from the children.
3293 Supported summary types are:
3294 {+} Sum numbers in this column.
3295 {:} Sum times, HH:MM:SS, plain numbers are hours.
3296 {X} Checkbox status, [X] if all children are [X].
3298 Here is an example for a complete columns definition, along with allowed
3301 :COLUMNS: %20ITEM %9Approved(Approved?){X} %Owner %11Status %10Time_Spent{:}
3302 :Owner_ALL: Tammy Mark Karl Lisa Don
3303 :Status_ALL: "In progress" "Not started yet" "Finished" ""
3304 :Approved_ALL: "[ ]" "[X]"
3306 The first column, `%25ITEM', means the first 25 characters of the
3307 item itself, i.e. of the headline. You probably always should start the
3308 column definition with the ITEM specifier. The other specifiers create
3309 columns `Owner' with a list of names as allowed values, for `Status'
3310 with four different possible values, and for a checkbox field
3311 `Approved'. When no width is given after the `%' character, the column
3312 will be exactly as wide as it needs to be in order to fully display all
3313 values. The `Approved' column does have a modified title (`Approved?',
3314 with a question mark). Summaries will be created for the `Time_Spent'
3315 column by adding time duration expressions like HH:MM, and for the
3316 `Approved' column, by providing an `[X]' status if all children have
3320 File: org, Node: Using column view, Prev: Defining columns, Up: Column view
3322 7.4.2 Using Column View
3323 -----------------------
3325 Turning column view on and off
3326 ..............................
3329 Create the column view for the local environment. This command
3330 searches the hierarchy, up from point, for a `COLUMNS' property
3331 that defines a format. When one is found, the column view table
3332 is established for the entire tree, starting from the entry that
3333 contains the `COLUMNS' property. If none is found, the format is
3334 taken from the `#+COLUMNS' line or from the variable
3335 `org-columns-default-format', and column view is established for
3336 the current entry and its subtree.
3344 `<left> <right> <up> <down>'
3345 Move through the column view from field to field.
3348 Switch to the next/previous allowed value of the field. For this,
3349 you have to have specified allowed values for a property.
3352 Same as `S-<left>/<right>'
3355 Edit the property at point. For the special properties, this will
3356 invoke the same interface that you normally use to change that
3357 property. For example, when editing a TAGS property, the tag
3358 completion or fast selection interface will pop up.
3361 View the full value of this property. This is useful if the width
3362 of the column is smaller than that of the value.
3365 Edit the list of allowed values for this property. If the list is
3366 found in the hierarchy, the modified values is stored there. If
3367 no list is found, the new value is stored in the first entry that
3368 is part of the current column view.
3370 Modifying the table structure
3371 .............................
3374 Make the column narrower/wider by one character.
3377 Insert a new column, to the right of the current column.
3380 Delete the current column.
3383 File: org, Node: Property API, Prev: Column view, Up: Properties and columns
3385 7.5 The Property API
3386 ====================
3388 There is a full API for accessing and changing properties. This API can
3389 be used by Emacs Lisp programs to work with properties and to implement
3390 features based on them. For more information see *Note Using the
3394 File: org, Node: Timestamps, Next: Remember, Prev: Properties and columns, Up: Top
3399 Items can be labeled with timestamps to make them useful for project
3404 * Time stamps:: Assigning a time to a tree entry
3405 * Creating timestamps:: Commands which insert timestamps
3406 * Deadlines and scheduling:: Planning your work
3407 * Clocking work time::
3410 File: org, Node: Time stamps, Next: Creating timestamps, Prev: Timestamps, Up: Timestamps
3412 8.1 Time stamps, deadlines and scheduling
3413 =========================================
3415 A time stamp is a specification of a date (possibly with time or a range
3416 of times) in a special format, either `<2003-09-16 Tue>' or
3417 `<2003-09-16 Tue 09:39>' or `<2003-09-16 Tue 12:00-12:30>'(1). A time
3418 stamp can appear anywhere in the headline or body of an org-tree entry.
3419 Its presence causes entries to be shown on specific dates in the agenda
3420 (*note Weekly/Daily agenda::). We distinguish:
3422 PLAIN TIME STAMP, EVENT, APPOINTMENT
3423 A simple time stamp just assigns a date/time to an item. This is
3424 just like writing down an appointment or event in a paper agenda.
3425 In the timeline and agenda displays, the headline of an entry
3426 associated with a plain time stamp will be shown exactly on that
3429 * Meet Peter at the movies <2006-11-01 Wed 19:15>
3430 * Discussion on climate change <2006-11-02 Thu 20:00-22:00>
3432 TIME STAMP WITH REPEATER INTERVAL
3433 A time stamp may contain a _repeater interval_, indicating that it
3434 applies not only on the given date, but again and again after a
3435 certain interval of N days (d), weeks (w), months(m), or years(y).
3436 The following will show up in the agenda every Wednesday:
3438 * Pick up Sam at school <2007-05-16 Wed 12:30 +1w>
3440 DIARY-STYLE SEXP ENTRIES
3441 For more complex date specifications, Org-mode supports using the
3442 special sexp diary entries implemented in the Emacs calendar/diary
3443 package. For example
3445 * The nerd meeting on every 2nd Thursday of the month
3446 <%%(diary-float t 4 2)>
3449 Two time stamps connected by `--' denote a range. The headline
3450 will be shown on the first and last day of the range, and on any
3451 dates that are displayed and fall in the range. Here is an
3454 ** Meeting in Amsterdam
3455 <2004-08-23 Mon>--<2004-08-26 Thu>
3458 Just like a plain time stamp, but with square brackets instead of
3459 angular ones. These time stamps are inactive in the sense that
3460 they do _not_ trigger an entry to show up in the agenda.
3462 * Gillian comes late for the fifth time [2006-11-01 Wed]
3465 ---------- Footnotes ----------
3467 (1) This is the standard ISO date/time format. If you cannot get
3468 used to these, see *Note Custom time format::
3471 File: org, Node: Creating timestamps, Next: Deadlines and scheduling, Prev: Time stamps, Up: Timestamps
3473 8.2 Creating timestamps
3474 =======================
3476 For Org-mode to recognize time stamps, they need to be in the specific
3477 format. All commands listed below produce time stamps in the correct
3481 Prompt for a date and insert a corresponding time stamp. When the
3482 cursor is at a previously used time stamp, it is updated to NOW.
3483 When this command is used twice in succession, a time range is
3487 Like `C-c .', but use the alternative format which contains date
3488 and time. The default time can be rounded to multiples of 5
3489 minutes, see the option `org-time-stamp-rounding-minutes'.
3492 Like `C-c .', but insert an inactive time stamp that will not cause
3496 Insert a time stamp corresponding to the cursor date in the
3500 Access the Emacs calendar for the current date. If there is a
3501 timestamp in the current line, goto the corresponding date instead.
3504 Access the agenda for the date given by the time stamp or -range at
3505 point (*note Weekly/Daily agenda::).
3509 Change date at cursor by one day. These key bindings conflict with
3510 CUA-mode (*note Conflicts::).
3514 Change the item under the cursor in a timestamp. The cursor can
3515 be on a year, month, day, hour or minute. Note that if the cursor
3516 is in a headline and not at a time stamp, these same keys modify
3517 the priority of an item. (*note Priorities::). The key bindings
3518 also conflict with CUA-mode (*note Conflicts::).
3521 Evaluate a time range by computing the difference between start and
3522 end. With prefix arg, insert result after the time range (in a
3523 table: into the following column).
3527 * The date/time prompt:: How org-mode helps you entering date and time
3528 * Custom time format:: Making dates look differently
3531 File: org, Node: The date/time prompt, Next: Custom time format, Prev: Creating timestamps, Up: Creating timestamps
3533 8.2.1 The date/time prompt
3534 --------------------------
3536 When Org-mode prompts for a date/time, the prompt suggests to enter an
3537 ISO date. But it will in fact accept any string containing some date
3538 and/or time information. You can, for example, use `C-y' to paste a
3539 (possibly multi-line) string copied from an email message. Org-mode
3540 will find whatever information is in there and will replace anything not
3541 specified with the _default date and time_. The default is usually the
3542 current date and time, but when modifying an existing time stamp, or
3543 when entering the second stamp of a range, it is taken from the stamp in
3544 the buffer. For example:
3546 3-2-5 --> 2003-02-05
3547 feb 15 --> defaultyear-02-15
3548 sep 12 9 --> 2009-09-12
3549 12:45 --> default-date 12:45
3550 22 sept 0:34 --> defaultyear-09-22 0:34
3551 12 --> defaultyear-defaultmonth-12
3552 Fri --> nearest Friday (defaultdate or later)
3554 Furthermore you can specify a relative date by giving, as the
3555 _first_ thing in the input: a plus/minus sign, a number and a letter
3556 [dwmy] to indicate change in days weeks, months, years. With a single
3557 plus or minus, the date is always relative to today. With a double
3558 plus or minus, it is relative to the default date. E.g.
3560 +4d --> four days from today
3561 +4 --> same as above
3562 +2w --> two weeks from today
3563 ++5 --> five days from default date
3565 The function understands English month and weekday abbreviations. If
3566 you want to use unabbreviated names and/or other languages, configure
3567 the variables `parse-time-months' and `parse-time-weekdays'.
3569 Parallel to the minibuffer prompt, a calendar is popped up(1). When
3570 you exit the date prompt, either by clicking on a date in the calendar,
3571 or by pressing <RET>, the date selected in the calendar will be
3572 combined with the information entered at the prompt. You can control
3573 the calendar fully from the minibuffer:
3576 Scroll calendar backwards by one month.
3579 Scroll calendar forwards by one month.
3582 Select date by clicking on it.
3603 Choose date in calendar (only if nothing was typed into
3606 ---------- Footnotes ----------
3608 (1) If you don't need/want the calendar, configure the variable
3609 `org-popup-calendar-for-date-prompt'.
3612 File: org, Node: Custom time format, Prev: The date/time prompt, Up: Creating timestamps
3614 8.2.2 Custom time format
3615 ------------------------
3617 Org-mode uses the standard ISO notation for dates and times as it is
3618 defined in ISO 8601. If you cannot get used to this and require another
3619 representation of date and time to keep you happy, you can get it by
3620 customizing the variables `org-display-custom-times' and
3621 `org-time-stamp-custom-formats'.
3624 Toggle the display of custom formats for dates and times.
3626 Org-mode needs the default format for scanning, so the custom date/time
3627 format does not _replace_ the default format - instead it is put _over_
3628 the default format using text properties. This has the following
3630 * You cannot place the cursor onto a time stamp anymore, only before
3633 * The `S-<up>/<down>' keys can no longer be used to adjust each
3634 component of a time stamp. If the cursor is at the beginning of
3635 the stamp, `S-<up>/<down>' will change the stamp by one day, just
3636 like `S-<left>/<right>'. At the end of the stamp, the time will
3637 be changed by one minute.
3639 * If the time stamp contains a range of clock times or a repeater,
3640 these will not be overlayed, but remain in the buffer as they were.
3642 * When you delete a time stamp character-by-character, it will only
3643 disappear from the buffer after _all_ (invisible) characters
3644 belonging to the ISO timestamp have been removed.
3646 * If the custom time stamp format is longer than the default and you
3647 are using dates in tables, table alignment will be messed up. If
3648 the custom format is shorter, things do work as expected.
3651 File: org, Node: Deadlines and scheduling, Next: Clocking work time, Prev: Creating timestamps, Up: Timestamps
3653 8.3 Deadlines and Scheduling
3654 ============================
3656 A time stamp may be preceded by special keywords to facilitate planning
3660 The task (most likely a TODO item) is supposed to be finished on
3661 that date, and it will be listed then. In addition, the
3662 compilation for _today_ will carry a warning about the approaching
3663 or missed deadline, starting `org-deadline-warning-days' before
3664 the due date, and continuing until the entry is marked DONE. An
3667 *** TODO write article about the Earth for the Guide
3668 The editor in charge is [[bbdb:Ford Prefect]]
3669 DEADLINE: <2004-02-29 Sun>
3671 You can specify a different lead time for warnings for a specific
3672 deadlines using the following syntax. Here is an example with a
3673 warning period of 5 days `DEADLINE: <2004-02-29 Sun -5d>'.
3676 You are planning to start working on that task on the given date.
3677 The headline will be listed under the given date(1). In addition,
3678 a reminder that the scheduled date has passed will be present in
3679 the compilation for _today_, until the entry is marked DONE.
3680 I.e., the task will automatically be forwarded until completed.
3682 *** TODO Call Trillian for a date on New Years Eve.
3683 SCHEDULED: <2004-12-25 Sat>
3685 Important: Scheduling an item in Org-mode should not be understood
3686 like Scheduling a meeting. Setting a date for a meeting is just a
3687 simple appointment, you should mark this entry with a simple plain
3688 time stamp, to get this item shown on the date where it applies.
3689 This is a frequent mis-understanding from Org-users. In Org-mode,
3690 Scheduling means setting a date when you want to start working on
3695 * Inserting deadline/schedule:: Planning items
3696 * Repeated tasks:: Items that show up again and again
3698 ---------- Footnotes ----------
3700 (1) It will still be listed on that date after it has been marked
3701 DONE. If you don't like this, set the variable
3702 `org-agenda-skip-scheduled-if-done'.
3705 File: org, Node: Inserting deadline/schedule, Next: Repeated tasks, Prev: Deadlines and scheduling, Up: Deadlines and scheduling
3707 8.3.1 Inserting deadline/schedule
3708 ---------------------------------
3710 The following commands allow to quickly insert a deadline or to schedule
3714 Insert `DEADLINE' keyword along with a stamp. The insertion will
3715 happen in the line directly following the headline. When called
3716 with a prefix arg, an existing deadline will be removed from the
3720 Create a sparse tree with all deadlines that are either past-due,
3721 or which will become due within `org-deadline-warning-days'. With
3722 `C-u' prefix, show all deadlines in the file. With a numeric
3723 prefix, check that many days. For example, `C-1 C-c C-w' shows
3724 all deadlines due tomorrow.
3727 Insert `SCHEDULED' keyword along with a stamp. The insertion will
3728 happen in the line directly following the headline. Any CLOSED
3729 timestamp will be removed. When called with a prefix argument,
3730 remove the scheduling date from the entry.
3733 File: org, Node: Repeated tasks, Prev: Inserting deadline/schedule, Up: Deadlines and scheduling
3735 8.3.2 Repeated Tasks
3736 --------------------
3738 Some tasks need to be repeated again and again, and Org-mode therefore
3739 allows to use a repeater in a DEADLINE or SCHEDULED time stamp, for
3741 ** TODO Pay the rent
3742 DEADLINE: <2005-10-01 Sat +1m>
3744 Deadlines and scheduled items produce entries in the agenda when they
3745 are over-due, so it is important to be able to mark such an entry as
3746 completed once you have done so. When you mark a DEADLINE or a SCHEDULE
3747 with the todo keyword DONE, it will no longer produce entries in the
3748 agenda. The problem with this is, however, that then also the _next_
3749 instance of the repeated entry will not be active. Org-mode deals with
3750 this in the following way: When you try to mark such an entry DONE
3751 (using `C-c C-t'), it will shift the base date of the repeating time
3752 stamp by the repeater interval, and immediately set the entry state
3753 back to TODO. In the example above, setting the state to DONE would
3754 actually switch the date like this:
3756 ** TODO Pay the rent
3757 DEADLINE: <2005-11-01 Tue +1m>
3759 You will also be prompted for a note(1) that will be put under the
3760 DEADLINE line to keep a record that you actually acted on the previous
3761 instance of this deadline.
3763 As a consequence of shifting the base date, this entry will no
3764 longer be visible in the agenda when checking past dates, but all
3765 future instances will be visible.
3767 You may have both scheduling and deadline information for a specific
3768 task - just make sure that the repeater intervals on both are the same.
3770 ---------- Footnotes ----------
3772 (1) You can change this using the option `org-log-repeat', or the
3773 `#+STARTUP' options `logrepeat' and `nologrepeat'.
3776 File: org, Node: Clocking work time, Prev: Deadlines and scheduling, Up: Timestamps
3778 8.4 Clocking work time
3779 ======================
3781 Org-mode allows you to clock the time you spent on specific tasks in a
3782 project. When you start working on an item, you can start the clock.
3783 When you stop working on that task, or when you mark the task done, the
3784 clock is stopped and the corresponding time interval is recorded. It
3785 also computes the total time spent on each subtree of a project.
3788 Start the clock on the current item (clock-in). This inserts the
3789 CLOCK keyword together with a timestamp. If this is not the first
3790 clocking of this item, the multiple CLOCK lines will be wrapped
3791 into a `:CLOCK:' drawer (see also the variable
3792 `org-clock-into-drawer'.
3795 Stop the clock (clock-out). The inserts another timestamp at the
3796 same location where the clock was last started. It also directly
3797 computes the resulting time in inserts it after the time range as
3798 `=> HH:MM'. See the variable `org-log-done' for the possibility to
3799 record an additional note together with the clock-out time
3803 Recompute the time interval after changing one of the time stamps.
3804 This is only necessary if you edit the time stamps directly. If
3805 you change them with `S-<cursor>' keys, the update is automatic.
3808 Changing the TODO state of an item to DONE automatically stops the
3809 clock if it is running in this same item.
3812 Cancel the current clock. This is useful if a clock was started by
3813 mistake, or if you ended up working on something else.
3816 Jump to the entry that contains the currently running clock, an
3820 Display time summaries for each subtree in the current buffer.
3821 This puts overlays at the end of each headline, showing the total
3822 time recorded under that heading, including the time of any
3823 subheadings. You can use visibility cycling to study the tree, but
3824 the overlays disappear when you change the buffer (see variable
3825 `org-remove-highlights-with-change') or press `C-c C-c'.
3828 Insert a dynamic block (*note Dynamic blocks::) containing a clock
3829 report as an org-mode table into the current file. When the
3830 cursor is at an existing clock table, just update it. When called
3831 with a prefix argument, jump to the first clock report in the
3832 current document and update it.
3833 #+BEGIN: clocktable :maxlevel 2 :emphasize nil :scope file
3836 If such a block already exists at point, its content is replaced
3837 by the new table. The `BEGIN' line can specify options:
3838 :maxlevel Maximum level depth to which times are listed in the table.
3839 :emphasize When `t', emphasize level one and level two items
3840 :scope The scope to consider. This can be any of the following:
3841 nil the current buffer or narrowed region
3842 file the full current buffer
3843 subtree the subtree where the clocktable is located
3844 treeN the surrounding level N tree, for example `tree3'
3845 tree the surrounding level 1 tree
3846 agenda all agenda files
3847 ("file"..) scan these files
3848 :block The time block to consider. This block is specified relative
3849 to the current time and may be any of these keywords:
3850 `today', `yesterday', `thisweek', `lastweek',
3851 `thismonth', `lastmonth', `thisyear', or `lastyear'.
3852 :tstart A time string specifying when to start considering times
3853 :tend A time string specifying when to stop considering times
3854 So to get a clock summary of the current level 1 tree, for the
3855 current day, you could write
3856 #+BEGIN: clocktable :maxlevel 2 :block today :scope tree1
3859 and to use a specific time range you could write(2)
3860 #+BEGIN: clocktable :tstart "<2006-08-10 Thu 10:00>"
3861 :tend "<2006-08-10 Thu 12:00>"
3867 Update dynamical block at point. The cursor needs to be in the
3868 `#+BEGIN' line of the dynamic block.
3871 Update all dynamic blocks (*note Dynamic blocks::). This is
3872 useful if you have several clocktable blocks in a buffer.
3874 The `l' key may be used in the timeline (*note Timeline::) and in
3875 the agenda (*note Weekly/Daily agenda::) to show which tasks have been
3876 worked on or closed during a day.
3878 ---------- Footnotes ----------
3880 (1) The corresponding in-buffer setting is: `#+STARTUP:
3883 (2) Note that all parameters must be specified in a single line -
3884 the line is broken here only to fit it onto the manual.
3887 File: org, Node: Remember, Next: Agenda views, Prev: Timestamps, Up: Top
3892 The Remember package by John Wiegley lets you store quick notes with
3893 little interruption of your work flow. See
3894 `http://www.emacswiki.org/cgi-bin/wiki/RememberMode' for more
3895 information. It is an excellent way to add new notes and TODO items to
3896 Org-mode files. Org-mode significantly expands the possibilities of
3897 remember: You may define templates for different note types, and
3898 associate target files and headlines with specific templates. It also
3899 allows you to select the location where a note should be stored
3900 interactively, on the fly.
3904 * Setting up remember:: Some code for .emacs to get things going
3905 * Remember templates:: Define the outline of different note types
3906 * Storing notes:: Directly get the note to where it belongs
3909 File: org, Node: Setting up remember, Next: Remember templates, Prev: Remember, Up: Remember
3911 9.1 Setting up remember
3912 =======================
3914 The following customization will tell remember to use org files as
3915 target, and to create annotations compatible with Org-mode links.
3917 (setq org-directory "~/path/to/my/orgfiles/")
3918 (setq org-default-notes-file (concat org-directory "/notes.org"))
3919 (setq remember-annotation-functions '(org-remember-annotation))
3920 (setq remember-handler-functions '(org-remember-handler))
3921 (add-hook 'remember-mode-hook 'org-remember-apply-template)
3924 File: org, Node: Remember templates, Next: Storing notes, Prev: Setting up remember, Up: Remember
3926 9.2 Remember templates
3927 ======================
3929 In combination with Org-mode, you can use templates to generate
3930 different types of remember notes. For example, if you would like to
3931 use one template to create general TODO entries, another one for
3932 journal entries, and a third one for collecting random ideas, you could
3935 (setq org-remember-templates
3936 '(("Todo" ?t "* TODO %?\n %i\n %a" "~/org/TODO.org" "Tasks")
3937 ("Journal" ?j "* %U %?\n\n %i\n %a" "~/org/JOURNAL.org")
3938 ("Idea" ?i "* %^{Title}\n %i\n %a" "~/org/JOURNAL.org" "New Ideas")))
3940 In these entries, the first string is just a name, and the character
3941 specifies how to select the template. It is useful if the character is
3942 also the first letter of the name. The next string specifies the
3943 template. Two more (optional) strings give the file in which, and the
3944 headline under which the new note should be stored. The file defaults
3945 (if not present or `nil') to `org-default-notes-file', the heading to
3946 `org-remember-default-headline'. Both defaults help to get to the
3947 storing location quickly, but you can change the location interactively
3948 while storing the note.
3950 When you call `M-x remember' (or `M-x org-remember') to remember
3951 something, org will prompt for a key to select the template (if you have
3952 more than one template) and then prepare the buffer like
3954 [[file:link to where you called remember]]
3956 During expansion of the template, special `%'-escapes allow dynamic
3957 insertion of content:
3958 %^{prompt} prompt the user for a string and replace this sequence with it.
3959 %t time stamp, date only
3960 %T time stamp with date and time
3961 %u, %U like the above, but inactive time stamps
3962 %^t like `%t', but prompt for date. Similarly `%^T', `%^u', `%^U'
3963 You may define a prompt like `%^{Birthday}t'
3964 %n user name (taken from `user-full-name')
3965 %a annotation, normally the link created with `org-store-link'
3966 %A like `%a', but prompt for the description part
3967 %i initial content, the region when remember is called with C-u.
3968 The entire text will be indented like `%i' itself.
3969 %^g prompt for tags, with completion on tags in target file.
3970 %^G prompt for tags, with completion all tags in all agenda files.
3971 %:keyword specific information for certain link types, see below
3973 For specific link types, the following keywords will be defined(1):
3975 Link type | Available keywords
3976 -------------------+----------------------------------------------
3977 bbdb | %:name %:company
3978 vm, wl, mh, rmail | %:type %:subject %:message-id
3979 | %:from %:fromname %:fromaddress
3980 | %:to %:toname %:toaddress
3981 | %:fromto (either "to NAME" or "from NAME")(2)
3982 gnus | %:group, for messages also all email fields
3984 info | %:file %:node
3987 To place the cursor after template expansion use:
3989 %? After completing the template, position cursor here.
3991 If you change you mind about which template to use, call `org-remember'
3992 in the remember buffer. You may then select a new template that will
3993 be filled with the previous context information.
3995 ---------- Footnotes ----------
3997 (1) If you define your own link types (*note Adding hyperlink
3998 types::), any property you store with `org-store-link-props' can be
3999 accessed in remember templates in a similar way.
4001 (2) This will always be the other, not the user. See the variable
4002 `org-from-is-user-regexp'.
4005 File: org, Node: Storing notes, Prev: Remember templates, Up: Remember
4010 When you are finished preparing a note with remember, you have to press
4011 `C-c C-c' to file the note away. The handler will store the note in
4012 the file and under the headline specified in the template, or it will
4013 use the default file and headlines. The window configuration will be
4014 restored, and you are back in the working context before the call to
4015 `remember'. To re-use the location found during the last call to
4016 `remember', exit the remember buffer with `C-u C-u C-c C-c', i.e.
4017 specify a double prefix argument to `C-c C-c'.
4019 If you want to store the note to a different place, use `C-u C-c
4020 C-c' instead to exit remember(1). The handler will then first prompt
4021 for a target file - if you press <RET>, the value specified for the
4022 template is used. Then the command offers the headings tree of the
4023 selected file, with the cursor position at the default headline (if you
4024 had specified one in the template). You can either immediately press
4025 <RET> to get the note placed there. Or you can use the following keys
4026 to find a different location:
4027 <TAB> Cycle visibility.
4028 <down> / <up> Next/previous visible headline.
4029 n / p Next/previous visible headline.
4030 f / b Next/previous headline same level.
4032 Pressing <RET> or <left> or <right> then leads to the following
4035 Cursor Key Note gets inserted
4037 on headline <RET> as sublevel of the heading at cursor, first or
4039 depending on `org-reverse-note-order'.
4040 <left>/<right>as same level, before/after current heading
4041 buffer-start <RET> as level 2 heading at end of file or level 1
4043 depending on `org-reverse-note-order'.
4044 not on <RET> at cursor position, level taken from context.
4047 Before inserting the text into a tree, the function ensures that the
4048 text has a headline, i.e. a first line that starts with a `*'. If not,
4049 a headline is constructed from the current date and some additional
4050 data. If you have indented the text of the note below the headline, the
4051 indentation will be adapted if inserting the note into the tree requires
4052 demotion from level 1.
4054 ---------- Footnotes ----------
4056 (1) Configure the variable `org-remember-store-without-prompt' to
4057 make this behavior the default.
4060 File: org, Node: Agenda views, Next: Embedded LaTeX, Prev: Remember, Up: Top
4065 Due to the way Org-mode works, TODO items, time-stamped items, and
4066 tagged headlines can be scattered throughout a file or even a number of
4067 files. To get an overview over open action items, or over events that
4068 are important for a particular date, this information must be collected,
4069 sorted and displayed in an organized way.
4071 Org-mode can select items based on various criteria, and display them
4072 in a separate buffer. Six different view types are provided:
4074 * an _agenda_ that is like a calendar and shows information for
4077 * a _TODO list_ that covers all unfinished action items,
4079 * a _tags view_, showings headlines based on the tags associated
4082 * a _timeline view_ that shows all events in a single Org-mode file,
4083 in time-sorted view,
4085 * a _stuck projects view_ showing projects that currently don't move
4088 * _custom views_ that are special tag/keyword searches and
4089 combinations of different views.
4091 The extracted information is displayed in a special _agenda buffer_.
4092 This buffer is read-only, but provides commands to visit the
4093 corresponding locations in the original Org-mode files, and even to
4094 edit these files remotely.
4096 Two variables control how the agenda buffer is displayed and whether
4097 the window configuration is restored when the agenda exits:
4098 `org-agenda-window-setup' and `org-agenda-restore-windows-after-quit'.
4102 * Agenda files:: Files being searched for agenda information
4103 * Agenda dispatcher:: Keyboard access to agenda views
4104 * Built-in agenda views:: What is available out of the box?
4105 * Presentation and sorting:: How agenda items are prepared for display
4106 * Agenda commands:: Remote editing of org trees
4107 * Custom agenda views:: Defining special searches and views
4110 File: org, Node: Agenda files, Next: Agenda dispatcher, Prev: Agenda views, Up: Agenda views
4115 The information to be shown is collected from all _agenda files_, the
4116 files listed in the variable `org-agenda-files'(1). Thus even if you
4117 only work with a single Org-mode file, this file should be put into
4118 that list(2). You can customize `org-agenda-files', but the easiest
4119 way to maintain it is through the following commands
4122 Add current file to the list of agenda files. The file is added to
4123 the front of the list. If it was already in the list, it is moved
4124 to the front. With prefix arg, file is added/moved to the end.
4127 Remove current file from the list of agenda files.
4131 Cycle through agenda file list, visiting one file after the other.
4133 The Org menu contains the current list of files and can be used to
4136 ---------- Footnotes ----------
4138 (1) If the value of that variable is not a list, but a single file
4139 name, then the list of agenda files will be maintained in that external
4142 (2) When using the dispatcher, pressing `1' before selecting a
4143 command will actually limit the command to the current file, and ignore
4144 `org-agenda-files' until the next dispatcher command.
4147 File: org, Node: Agenda dispatcher, Next: Built-in agenda views, Prev: Agenda files, Up: Agenda views
4149 10.2 The agenda dispatcher
4150 ==========================
4152 The views are created through a dispatcher that should be bound to a
4153 global key, for example `C-c a' (*note Installation::). In the
4154 following we will assume that `C-c a' is indeed how the dispatcher is
4155 accessed and list keyboard access to commands accordingly. After
4156 pressing `C-c a', an additional letter is required to execute a
4157 command. The dispatcher offers the following default commands:
4159 Create the calendar-like agenda (*note Weekly/Daily agenda::).
4162 Create a list of all TODO items (*note Global TODO list::).
4165 Create a list of headlines matching a TAGS expression (*note
4166 Matching tags and properties::).
4169 Create the timeline view for the current buffer (*note Timeline::).
4172 Create a list of stuck projects (*note Stuck projects::).
4175 Search for a regular expression in all agenda files and
4176 additionally in the files listed in
4177 `org-agenda-multi-occur-extra-files'. This uses the Emacs command
4178 `multi-occur'. A prefix argument can be used to specify the
4179 number of context lines for each match, default is 1.
4182 Restrict an agenda command to the current buffer. After pressing
4183 `1', you still need to press the character selecting the command.
4186 If there is an active region, restrict the following agenda
4187 command to the region. Otherwise, restrict it to the current
4188 subtree. After pressing `0', you still need to press the
4189 character selecting the command.
4191 You can also define custom commands that will be accessible through
4192 the dispatcher, just like the default commands. This includes the
4193 possibility to create extended agenda buffers that contain several
4194 blocks together, for example the weekly agenda, the global TODO list and
4195 a number of special tags matches. *Note Custom agenda views::.
4198 File: org, Node: Built-in agenda views, Next: Presentation and sorting, Prev: Agenda dispatcher, Up: Agenda views
4200 10.3 The built-in agenda views
4201 ==============================
4203 In this section we describe the built-in views.
4207 * Weekly/Daily agenda:: The calendar page with current tasks
4208 * Global TODO list:: All unfinished action items
4209 * Matching tags and properties:: Structured information with fine-tuned search
4210 * Timeline:: Time-sorted view for single file
4211 * Stuck projects:: Find projects you need to review
4214 File: org, Node: Weekly/Daily agenda, Next: Global TODO list, Prev: Built-in agenda views, Up: Built-in agenda views
4216 10.3.1 The weekly/daily agenda
4217 ------------------------------
4219 The purpose of the weekly/daily _agenda_ is to act like a page of a
4220 paper agenda, showing all the tasks for the current week or day.
4223 Compile an agenda for the current week from a list of org files.
4224 The agenda shows the entries for each day. With a `C-u' prefix (or
4225 when the variable `org-agenda-include-all-todo' is `t'), all
4226 unfinished TODO items (including those without a date) are also
4227 listed at the beginning of the buffer, before the first date.
4229 Remote editing from the agenda buffer means, for example, that you
4230 can change the dates of deadlines and appointments from the agenda
4231 buffer. The commands available in the Agenda buffer are listed in
4232 *Note Agenda commands::.
4234 Calendar/Diary integration
4235 ..........................
4237 Emacs contains the calendar and diary by Edward M. Reingold. The
4238 calendar displays a three-month calendar with holidays from different
4239 countries and cultures. The diary allows you to keep track of
4240 anniversaries, lunar phases, sunrise/set, recurrent appointments
4241 (weekly, monthly) and more. In this way, it is quite complementary to
4242 Org-mode. It can be very useful to combine output from Org-mode with
4245 In order to include entries from the Emacs diary into Org-mode's
4246 agenda, you only need to customize the variable
4248 (setq org-agenda-include-diary t)
4250 After that, everything will happen automatically. All diary entries
4251 including holidays, anniversaries etc will be included in the agenda
4252 buffer created by Org-mode. <SPC>, <TAB>, and <RET> can be used from
4253 the agenda buffer to jump to the diary file in order to edit existing
4254 diary entries. The `i' command to insert new entries for the current
4255 date works in the agenda buffer, as well as the commands `S', `M', and
4256 `C' to display Sunrise/Sunset times, show lunar phases and to convert
4257 to other calendars, respectively. `c' can be used to switch back and
4258 forth between calendar and agenda.
4260 If you are using the diary only for sexp entries and holidays, it is
4261 faster to not use the above setting, but instead to copy or even move
4262 the entries into an Org-mode file. Org-mode evaluates diary-style sexp
4263 entries, and does it faster because there is no overhead for first
4264 creating the diary display. Note that the sexp entries must start at
4265 the left margin, no white space is allowed before them. For example,
4266 the following segment of an Org-mode file will be processed and entries
4267 will be made in the agenda:
4269 * Birthdays and similar stuff
4271 %%(org-calendar-holiday) ; special function for holiday names
4273 %%(diary-anniversary 14 5 1956) Arthur Dent is %d years old
4274 %%(diary-anniversary 2 10 1869) Mahatma Gandhi would be %d years old
4276 Appointment reminders
4277 .....................
4279 Org can interact with Emacs appointments notification facility.
4281 To add all the appointments of your agenda files, use the command
4282 `org-agenda-to-appt'. This commands also lets you filter through the
4283 list of your appointments and add only those belonging to a specific
4284 category or matching a regular expression. See the docstring for
4288 File: org, Node: Global TODO list, Next: Matching tags and properties, Prev: Weekly/Daily agenda, Up: Built-in agenda views
4290 10.3.2 The global TODO list
4291 ---------------------------
4293 The global TODO list contains all unfinished TODO items, formatted and
4294 collected into a single place.
4297 Show the global TODO list. This collects the TODO items from all
4298 agenda files (*note Agenda views::) into a single buffer. The
4299 buffer is in `agenda-mode', so there are commands to examine and
4300 manipulate the TODO entries directly from that buffer (*note
4304 Like the above, but allows selection of a specific TODO keyword.
4305 You can also do this by specifying a prefix argument to `C-c a t'.
4306 With a `C-u' prefix you are prompted for a keyword, and you may
4307 also specify several keywords by separating them with `|' as
4308 boolean OR operator. With a numeric prefix, the Nth keyword in
4309 `org-todo-keywords' is selected. The `r' key in the agenda buffer
4310 regenerates it, and you can give a prefix argument to this command
4311 to change the selected TODO keyword, for example `3 r'. If you
4312 often need a search for a specific keyword, define a custom
4313 command for it (*note Agenda dispatcher::).
4314 Matching specific TODO keywords can also be done as part of a tags
4315 search (*note Tag searches::).
4317 Remote editing of TODO items means that you can change the state of a
4318 TODO entry with a single key press. The commands available in the TODO
4319 list are described in *Note Agenda commands::.
4321 Normally the global todo list simply shows all headlines with TODO
4322 keywords. This list can become very long. There are two ways to keep
4324 - Some people view a TODO item that has been _scheduled_ for
4325 execution (*note Time stamps::) as no longer _open_. Configure the
4326 variable `org-agenda-todo-ignore-scheduled' to exclude scheduled
4327 items from the global TODO list.
4329 - TODO items may have sublevels to break up the task into subtasks.
4330 In such cases it may be enough to list only the highest level TODO
4331 headline and omit the sublevels from the global list. Configure
4332 the variable `org-agenda-todo-list-sublevels' to get this behavior.
4335 File: org, Node: Matching tags and properties, Next: Timeline, Prev: Global TODO list, Up: Built-in agenda views
4337 10.3.3 Matching Tags and Properties
4338 -----------------------------------
4340 If headlines in the agenda files are marked with _tags_ (*note Tags::),
4341 you can select headlines based on the tags that apply to them and
4342 collect them into an agenda buffer.
4345 Produce a list of all headlines that match a given set of tags.
4346 The command prompts for a selection criterion, which is a boolean
4347 logic expression with tags, like `+WORK+URGENT-WITHBOSS' or
4348 `WORK|HOME' (*note Tags::). If you often need a specific search,
4349 define a custom command for it (*note Agenda dispatcher::).
4352 Like `C-c a m', but only select headlines that are also TODO items
4353 and force checking subitems (see variable
4354 `org-tags-match-list-sublevels'). Matching specific todo keywords
4355 together with a tags match is also possible, see *Note Tag
4358 The commands available in the tags list are described in *Note
4362 File: org, Node: Timeline, Next: Stuck projects, Prev: Matching tags and properties, Up: Built-in agenda views
4364 10.3.4 Timeline for a single file
4365 ---------------------------------
4367 The timeline summarizes all time-stamped items from a single Org-mode
4368 file in a _time-sorted view_. The main purpose of this command is to
4369 give an overview over events in a project.
4372 Show a time-sorted view of the org file, with all time-stamped
4373 items. When called with a `C-u' prefix, all unfinished TODO
4374 entries (scheduled or not) are also listed under the current date.
4376 The commands available in the timeline buffer are listed in *Note
4380 File: org, Node: Stuck projects, Prev: Timeline, Up: Built-in agenda views
4382 10.3.5 Stuck projects
4383 ---------------------
4385 If you are following a system like David Allen's GTD to organize your
4386 work, one of the "duties" you have is a regular review to make sure
4387 that all projects move along. A _stuck_ project is a project that has
4388 no defined next actions, so it will never show up in the TODO lists
4389 Org-mode produces. During the review, you need to identify such
4390 projects and define next actions for them.
4393 List projects that are stuck.
4396 Customize the variable `org-stuck-projects' to define what a stuck
4397 project is and how to find it.
4399 You almost certainly will have to configure this view before it will
4400 work for you. The built-in default assumes that all your projects are
4401 level-2 headlines, and that a project is not stuck if it has at least
4402 one entry marked with a todo keyword TODO or NEXT or NEXTACTION.
4404 Lets assume that you, in your own way of using Org-mode, identify
4405 projects with a tag PROJECT, and that you use a todo keyword MAYBE to
4406 indicate a project that should not be considered yet. Lets further
4407 assume that the todo keyword DONE marks finished projects, and that NEXT
4408 and TODO indicate next actions. The tag @SHOP indicates shopping and
4409 is a next action even without the NEXT tag. Finally, if the project
4410 contains the special word IGNORE anywhere, it should not be listed
4411 either. In this case you would start by identifying eligible projects
4412 with a tags/todo match `+PROJECT/-MAYBE-DONE', and then check for TODO,
4413 NEXT, @SHOP, and IGNORE in the subtree to identify projects that are
4414 not stuck. The correct customization for this is
4416 (setq org-stuck-projects
4417 '("+PROJECT/-MAYBE-DONE" ("NEXT" "TODO") ("@SHOP")
4421 File: org, Node: Presentation and sorting, Next: Agenda commands, Prev: Built-in agenda views, Up: Agenda views
4423 10.4 Presentation and sorting
4424 =============================
4426 Before displaying items in an agenda view, Org-mode visually prepares
4427 the items and sorts them. Each item occupies a single line. The line
4428 starts with a _prefix_ that contains the _category_ (*note
4429 Categories::) of the item and other important information. You can
4430 customize the prefix using the option `org-agenda-prefix-format'. The
4431 prefix is followed by a cleaned-up version of the outline headline
4432 associated with the item.
4436 * Categories:: Not all tasks are equal
4437 * Time-of-day specifications:: How the agenda knows the time
4438 * Sorting of agenda items:: The order of things
4441 File: org, Node: Categories, Next: Time-of-day specifications, Prev: Presentation and sorting, Up: Presentation and sorting
4446 The category is a broad label assigned to each agenda item. By default,
4447 the category is simply derived from the file name, but you can also
4448 specify it with a special line in the buffer, like this(1):
4452 If you would like to have a special CATEGORY for a single entry or a
4453 (sub)tree, give the entry a `:CATEGORY:' property with the location as
4454 the value (*note Properties and columns::).
4456 The display in the agenda buffer looks best if the category is not
4457 longer than 10 characters.
4459 ---------- Footnotes ----------
4461 (1) If there are several such lines in a file, each specifies the
4462 category for the text below it. The first category also applies to any
4463 text before the first CATEGORY line. This method is only kept for
4464 backward compatibility. The preferred method for setting multiple
4465 categories in a buffer is using a property.
4468 File: org, Node: Time-of-day specifications, Next: Sorting of agenda items, Prev: Categories, Up: Presentation and sorting
4470 10.4.2 Time-of-Day Specifications
4471 ---------------------------------
4473 Org-mode checks each agenda item for a time-of-day specification. The
4474 time can be part of the time stamp that triggered inclusion into the
4475 agenda, for example as in `<2005-05-10 Tue 19:00>'. Time ranges can be
4476 specified with two time stamps, like
4477 `<2005-05-10 Tue 20:30>--<2005-05-10 Tue 22:15>'.
4479 In the headline of the entry itself, a time(range) may also appear as
4480 plain text (like `12:45' or a `8:30-1pm'. If the agenda integrates the
4481 Emacs diary (*note Weekly/Daily agenda::), time specifications in diary
4482 entries are recognized as well.
4484 For agenda display, Org-mode extracts the time and displays it in a
4485 standard 24 hour format as part of the prefix. The example times in
4486 the previous paragraphs would end up in the agenda like this:
4488 8:30-13:00 Arthur Dent lies in front of the bulldozer
4489 12:45...... Ford Prefect arrives and takes Arthur to the pub
4490 19:00...... The Vogon reads his poem
4491 20:30-22:15 Marwin escorts the Hitchhikers to the bridge
4493 If the agenda is in single-day mode, or for the display of today, the
4494 timed entries are embedded in a time grid, like
4496 8:00...... ------------------
4497 8:30-13:00 Arthur Dent lies in front of the bulldozer
4498 10:00...... ------------------
4499 12:00...... ------------------
4500 12:45...... Ford Prefect arrives and takes Arthur to the pub
4501 14:00...... ------------------
4502 16:00...... ------------------
4503 18:00...... ------------------
4504 19:00...... The Vogon reads his poem
4505 20:00...... ------------------
4506 20:30-22:15 Marwin escorts the Hitchhikers to the bridge
4508 The time grid can be turned on and off with the variable
4509 `org-agenda-use-time-grid', and can be configured with
4510 `org-agenda-time-grid'.
4513 File: org, Node: Sorting of agenda items, Prev: Time-of-day specifications, Up: Presentation and sorting
4515 10.4.3 Sorting of agenda items
4516 ------------------------------
4518 Before being inserted into a view, the items are sorted. How this is
4519 done depends on the type of view.
4520 * For the daily/weekly agenda, the items for each day are sorted.
4521 The default order is to first collect all items containing an
4522 explicit time-of-day specification. These entries will be shown
4523 at the beginning of the list, as a _schedule_ for the day. After
4524 that, items remain grouped in categories, in the sequence given by
4525 `org-agenda-files'. Within each category, items are sorted by
4526 priority (*note Priorities::), which is composed of the base
4527 priority (2000 for priority `A', 1000 for `B', and 0 for `C'),
4528 plus additional increments for overdue scheduled or deadline items.
4530 * For the TODO list, items remain in the order of categories, but
4531 within each category, sorting takes place according to priority
4532 (*note Priorities::).
4534 * For tags matches, items are not sorted at all, but just appear in
4535 the sequence in which they are found in the agenda files.
4537 Sorting can be customized using the variable
4538 `org-agenda-sorting-strategy'.
4541 File: org, Node: Agenda commands, Next: Custom agenda views, Prev: Presentation and sorting, Up: Agenda views
4543 10.5 Commands in the agenda buffer
4544 ==================================
4546 Entries in the agenda buffer are linked back to the org file or diary
4547 file where they originate. You are not allowed to edit the agenda
4548 buffer itself, but commands are provided to show and jump to the
4549 original entry location, and to edit the org-files "remotely" from the
4550 agenda buffer. In this way, all information is stored only once,
4551 removing the risk that your agenda and note files may diverge.
4553 Some commands can be executed with mouse clicks on agenda lines. For
4554 the other commands, the cursor needs to be in the desired line.
4560 Next line (same as <up> and `C-p').
4563 Previous line (same as <down> and `C-n').
4570 Display the original location of the item in another window.
4573 Display original location and recenter that window.
4578 Go to the original location of the item in another window. Under
4579 Emacs 22, `mouse-1' will also works for this.
4582 Go to the original location of the item and delete other windows.
4585 Toggle Follow mode. In Follow mode, as you move the cursor through
4586 the agenda buffer, the other window always shows the corresponding
4587 location in the org file. The initial setting for this mode in new
4588 agenda buffers can be set with the variable
4589 `org-agenda-start-with-follow-mode'.
4592 Display the entire subtree of the current item in an indirect
4593 buffer. With numerical prefix ARG, go up to this level and then
4594 take that tree. If ARG is negative, go up that many levels. With
4595 `C-u' prefix, do not remove the previously used indirect buffer.
4598 Toggle Logbook mode. In Logbook mode, entries that where marked
4599 DONE while logging was on (variable `org-log-done') are shown in
4600 the agenda, as are entries that have been clocked on that day.
4606 Delete other windows.
4609 Switch to day/week/month/year view. When switching to day or week
4610 view, this setting becomes the default for subseqent agenda
4611 commands. Since month and year views are slow to create, the do
4612 not become the default.
4615 Toggle the inclusion of diary entries. See *Note Weekly/Daily
4619 Toggle the time grid on and off. See also the variables
4620 `org-agenda-use-time-grid' and `org-agenda-time-grid'.
4623 Recreate the agenda buffer, for example to reflect the changes
4624 after modification of the time stamps of items with S-<left> and
4625 S-<right>. When the buffer is the global todo list, a prefix
4626 argument is interpreted to create a selective list for a specific
4631 Save all Org-mode buffers in the current Emacs session.
4634 Display the following `org-agenda-ndays' days. For example, if
4635 the display covers a week, switch to the following week. With
4636 prefix arg, go forward that many times `org-agenda-ndays' days.
4639 Display the previous dates.
4651 Undo a change due to a remote editing command. The change is
4652 undone both in the agenda buffer and in the remote buffer.
4655 Change the TODO state of the item, both in the agenda and in the
4659 Delete the current agenda item along with the entire subtree
4660 belonging to it in the original Org-mode file. If the text to be
4661 deleted remotely is longer than one line, the kill needs to be
4662 confirmed by the user. See variable `org-agenda-confirm-kill'.
4665 Archive the subtree corresponding to the current headline.
4668 Show all tags associated with the current item. Because of
4669 inheritance, this may be more than the tags listed in the line
4673 Set tags for the current headline. If there is an active region
4674 in the agenda, change a tag for all headings in the region.
4677 Toggle the ARCHIVE tag for the current headline.
4680 Set the priority for the current item. Org-mode prompts for the
4681 priority character. If you reply with <SPC>, the priority cookie
4682 is removed from the entry.
4685 Display weighted priority of current item.
4689 Increase the priority of the current item. The priority is
4690 changed in the original buffer, but the agenda is not resorted.
4691 Use the `r' key for this.
4695 Decrease the priority of the current item.
4701 Set a deadline for this item.
4704 Change the time stamp associated with the current line by one day
4705 into the future. With prefix argument, change it by that many
4706 days. For example, `3 6 5 S-<right>' will change it by a year.
4707 The stamp is changed in the original org file, but the change is
4708 not directly reflected in the agenda buffer. Use the `r' key to
4712 Change the time stamp associated with the current line by one day
4716 Change the time stamp associated with the current line to today.
4717 The key `>' has been chosen, because it is the same as `S-.' on my
4721 Start the clock on the current item. If a clock is running
4722 already, it is stopped first.
4725 Stop the previously started clock.
4728 Cancel the currently running clock.
4731 Jump to the running clock in another window.
4737 Open the Emacs calendar and move to the date at the agenda cursor.
4740 When in the calendar, compute and show the Org-mode agenda for the
4744 Insert a new entry into the diary. Prompts for the type of entry
4745 (day, weekly, monthly, yearly, anniversary, cyclic) and creates a
4746 new entry in the diary, just as `i d' etc. would do in the
4747 calendar. The date is taken from the cursor position.
4750 Show the phases of the moon for the three months around current
4754 Show sunrise and sunset times. The geographical location must be
4755 set with calendar variables, see documentation of the Emacs
4759 Convert the date at cursor into many other cultural and historic
4763 Show holidays for three month around the cursor date.
4766 Export a single iCalendar file containing entries from all agenda
4773 Write the agenda view to a file. Depending on the extension of the
4774 selected file name, the view will be exported as HTML (extension
4775 `.html' or `.htm'), Postscript (extension `.ps'), or plain text
4776 (any other extension). Use the variable
4777 `org-agenda-exporter-settings' to set options for `ps-print' and
4778 for `htmlize' to be used during export.
4784 Quit agenda, remove the agenda buffer.
4787 Exit agenda, remove the agenda buffer and all buffers loaded by
4788 Emacs for the compilation of the agenda. Buffers created by the
4789 user to visit org files will not be removed.
4792 File: org, Node: Custom agenda views, Prev: Agenda commands, Up: Agenda views
4794 10.6 Custom agenda views
4795 ========================
4797 Custom agenda commands serve two purposes: to store and quickly access
4798 frequently used TODO and tags searches, and to create special composite
4799 agenda buffers. Custom agenda commands will be accessible through the
4800 dispatcher (*note Agenda dispatcher::), just like the default commands.
4804 * Storing searches:: Type once, use often
4805 * Block agenda:: All the stuff you need in a single buffer
4806 * Setting Options:: Changing the rules
4807 * Exporting Agenda Views:: Writing agendas to files.
4808 * Extracting Agenda Information for other programs::
4811 File: org, Node: Storing searches, Next: Block agenda, Prev: Custom agenda views, Up: Custom agenda views
4813 10.6.1 Storing searches
4814 -----------------------
4816 The first application of custom searches is the definition of keyboard
4817 shortcuts for frequently used searches, either creating an agenda
4818 buffer, or a sparse tree (the latter covering of course only the current
4819 buffer). Custom commands are configured in the variable
4820 `org-agenda-custom-commands'. You can customize this variable, for
4821 example by pressing `C-c a C'. You can also directly set it with Emacs
4822 Lisp in `.emacs'. The following example contains all valid search
4825 (setq org-agenda-custom-commands
4826 '(("w" todo "WAITING")
4827 ("W" todo-tree "WAITING")
4828 ("u" tags "+BOSS-URGENT")
4829 ("v" tags-todo "+BOSS-URGENT")
4830 ("U" tags-tree "+BOSS-URGENT")
4831 ("f" occur-tree "\\<FIXME\\>")))
4833 The initial single-character string in each entry defines the character
4834 you have to press after the dispatcher command `C-c a' in order to
4835 access the command. The second parameter is the search type, followed
4836 by the string or regular expression to be used for the matching. The
4837 example above will therefore define:
4840 as a global search for TODO entries with `WAITING' as the TODO
4844 as the same search, but only in the current buffer and displaying
4845 the results as a sparse tree
4848 as a global tags search for headlines marked `:BOSS:' but not
4852 as the same search as `C-c a u', but limiting the search to
4853 headlines that are also TODO items
4856 as the same search as `C-c a u', but only in the current buffer and
4857 displaying the result as a sparse tree
4860 to create a sparse tree (again: current buffer only) with all
4861 entries containing the word `FIXME'.
4864 File: org, Node: Block agenda, Next: Setting Options, Prev: Storing searches, Up: Custom agenda views
4869 Another possibility is the construction of agenda views that comprise
4870 the results of _several_ commands, each of which creates a block in the
4871 agenda buffer. The available commands include `agenda' for the daily
4872 or weekly agenda (as created with `C-c a a'), `alltodo' for the global
4873 todo list (as constructed with `C-c a t'), and the matching commands
4874 discussed above: `todo', `tags', and `tags-todo'. Here are two
4877 (setq org-agenda-custom-commands
4878 '(("h" "Agenda and Home-related tasks"
4882 ("o" "Agenda and Office-related tasks"
4887 This will define `C-c a h' to create a multi-block view for stuff you
4888 need to attend to at home. The resulting agenda buffer will contain
4889 your agenda for the current week, all TODO items that carry the tag
4890 `HOME', and also all lines tagged with `GARDEN'. Finally the command
4891 `C-c a o' provides a similar view for office tasks.
4894 File: org, Node: Setting Options, Next: Exporting Agenda Views, Prev: Block agenda, Up: Custom agenda views
4896 10.6.3 Setting Options for custom commands
4897 ------------------------------------------
4899 Org-mode contains a number of variables regulating agenda construction
4900 and display. The global variables define the behavior for all agenda
4901 commands, including the custom commands. However, if you want to change
4902 some settings just for a single custom view, you can do so. Setting
4903 options requires inserting a list of variable names and values at the
4904 right spot in `org-agenda-custom-commands'. For example:
4906 (setq org-agenda-custom-commands
4907 '(("w" todo "WAITING"
4908 ((org-agenda-sorting-strategy '(priority-down))
4909 (org-agenda-prefix-format " Mixed: ")))
4910 ("U" tags-tree "+BOSS-URGENT"
4911 ((org-show-following-heading nil)
4912 (org-show-hierarchy-above nil)))))
4914 Now the `C-c a w' command will sort the collected entries only by
4915 priority, and the prefix format is modified to just say ` Mixed:'
4916 instead of giving the category of the entry. The sparse tags tree of
4917 `C-c a U' will now turn out ultra-compact, because neither the headline
4918 hierarchy above the match, nor the headline following the match will be
4921 For command sets creating a block agenda,
4922 `org-agenda-custom-commands' has two separate spots for setting
4923 options. You can add options that should be valid for just a single
4924 command in the set, and options that should be valid for all commands in
4925 the set. The former are just added to the command entry, the latter
4926 must come after the list of command entries. Going back to the block
4927 agenda example (*note Block agenda::), let's change the sorting strategy
4928 for the `C-c a h' commands to `priority-down', but let's sort the
4929 results for GARDEN tags query in the opposite order, `priority-up'.
4930 This would look like this:
4932 (setq org-agenda-custom-commands
4933 '(("h" "Agenda and Home-related tasks"
4937 ((org-agenda-sorting-strategy '(priority-up)))))
4938 ((org-agenda-sorting-strategy '(priority-down))))
4939 ("o" "Agenda and Office-related tasks"
4944 As you see, the values and parenthesis setting is a little complex.
4945 When in doubt, use the customize interface to set this variable - it
4946 fully supports its structure. Just one caveat: When setting options in
4947 this interface, the _values_ are just lisp expressions. So if the
4948 value is a string, you need to add the double quotes around the value
4952 File: org, Node: Exporting Agenda Views, Next: Extracting Agenda Information for other programs, Prev: Setting Options, Up: Custom agenda views
4954 10.6.4 Exporting Agenda Views
4955 -----------------------------
4957 If you are away from your computer, it can be very useful to have a
4958 printed version of some agenda views to carry around. Org-mode can
4959 export custom agenda views as plain text, HTML(1) and postscript. If
4960 you want to do this only occasionally, use the command
4963 Write the agenda view to a file. Depending on the extension of the
4964 selected file name, the view will be exported as HTML (extension
4965 `.html' or `.htm'), Postscript (extension `.ps'), or plain text
4966 (any other extension). Use the variable
4967 `org-agenda-exporter-settings' to set options for `ps-print' and
4968 for `htmlize' to be used during export, for example
4969 (setq org-agenda-exporter-settings
4970 '((ps-number-of-columns 2)
4971 (ps-landscape-mode t)
4972 (htmlize-output-type 'css)))
4974 If you need to export certain agenda views frequently, you can
4975 associate any custom agenda command with a list of output file names
4976 (2). Here is an example that first does define custom commands for the
4977 agenda and the global todo list, together with a number of files to
4978 which to export them. Then we define two block agenda commands and
4979 specify filenames for them as well. File names can be relative to the
4980 current working directory, or absolute.
4982 (setq org-agenda-custom-commands
4983 '(("X" agenda "" nil ("agenda.html" "agenda.ps"))
4984 ("Y" alltodo "" nil ("todo.html" "todo.txt" "todo.ps"))
4985 ("h" "Agenda and Home-related tasks"
4990 ("~/views/home.html"))
4991 ("o" "Agenda and Office-related tasks"
4996 ("~/views/office.ps"))))
4998 The extension of the file name determines the type of export. If it
4999 is `.html', Org-mode will use the `htmlize.el' package to convert the
5000 buffer to HTML and save it to this file name. If the extension is
5001 `.ps', `ps-print-buffer-with-faces' is used to produce postscript
5002 output. Any other extension produces a plain ASCII file.
5004 The export files are _not_ created when you use one of those
5005 commands interactively. Instead, there is a special command to produce
5006 _all_ specified files in one step:
5009 Export all agenda views that have export filenames associated with
5012 You can use the options section of the custom agenda commands to also
5013 set options for the export commands. For example:
5015 (setq org-agenda-custom-commands
5017 ((ps-number-of-columns 2)
5018 (ps-landscape-mode t)
5019 (org-agenda-prefix-format " [ ] ")
5020 (org-agenda-with-colors nil)
5021 (org-agenda-remove-tags t))
5024 This command sets two options for the postscript exporter, to make it
5025 print in two columns in landscape format - the resulting page can be cut
5026 in two and then used in a paper agenda. The remaining settings modify
5027 the agenda prefix to omit category and scheduling information, and
5028 instead include a checkbox to check off items. We also remove the tags
5029 to make the lines compact, and we don't want to use colors for the
5030 black-and-white printer. Settings specified in
5031 `org-agenda-exporter-settings' will also apply, but the settings in
5032 `org-agenda-custom-commands' take precedence.
5034 From the command line you may also use
5035 emacs -f org-batch-store-agenda-views -kill
5036 or, if you need to modify some parameters
5037 emacs -eval '(org-batch-store-agenda-views \
5038 org-agenda-ndays 30 \
5039 org-agenda-include-diary nil \
5040 org-agenda-files (quote ("~/org/project.org")))' \
5042 which will create the agenda views restricted to the file
5043 `~/org/project.org', without diary entries and with 30 days extent.
5045 ---------- Footnotes ----------
5047 (1) You need to install Hrvoje Niksic' `htmlize.el'.
5049 (2) If you want to store standard views like the weekly agenda or
5050 the global TODO list as well, you need to define custom commands for
5051 them in order to be able to specify filenames.
5054 File: org, Node: Extracting Agenda Information for other programs, Prev: Exporting Agenda Views, Up: Custom agenda views
5056 10.6.5 Extracting Agenda Information for other programs
5057 -------------------------------------------------------
5059 Org-mode provides commands to access agenda information for the command
5060 line in emacs batch mode. This extracted information can be sent
5061 directly to a printer, or it can be read by a program that does further
5062 processing of the data. The first of these commands is the function
5063 `org-batch-agenda', that produces an agenda view and sends it as ASCII
5064 text to STDOUT. The command takes a single string as parameter. If
5065 the string has length 1, it is used as a key to one of the commands you
5066 have configured in `org-agenda-custom-commands', basically any key you
5067 can use after `C-c a'. For example, to directly print the current TODO
5070 emacs -batch -l ~/.emacs -eval '(org-batch-agenda "t")' | lpr
5072 If the parameter is a string with 2 or more characters, it is used
5073 as a tags/todo match string. For example, to print your local shopping
5074 list (all items with the tag `shop', but excluding the tag `NewYork'),
5077 emacs -batch -l ~/.emacs \
5078 -eval '(org-batch-agenda "+shop-NewYork")' | lpr
5080 You may also modify parameters on the fly like this:
5082 emacs -batch -l ~/.emacs \
5083 -eval '(org-batch-agenda "a" \
5084 org-agenda-ndays 30 \
5085 org-agenda-include-diary nil \
5086 org-agenda-files (quote ("~/org/project.org")))' \
5089 which will produce a 30 day agenda, fully restricted to the Org file
5090 `~/org/projects.org', not even including the diary.
5092 If you want to process the agenda data in more sophisticated ways,
5093 you can use the command `org-batch-agenda-csv' to get a comma-separated
5094 list of values for each agenda item. Each line in the output will
5095 contain a number of fields separated by commas. The fields in a line
5098 category The category of the item
5099 head The headline, without TODO kwd, TAGS and PRIORITY
5100 type The type of the agenda entry, can be
5101 todo selected in TODO match
5102 tagsmatch selected in tags match
5103 diary imported from diary
5106 timestamp appointment, selected by timestamp
5107 closed entry was closed on date
5108 upcoming-deadline warning about nearing deadline
5109 past-scheduled forwarded scheduled item
5110 block entry has date block including date
5111 todo The todo keyword, if any
5112 tags All tags including inherited ones, separated by colons
5113 date The relevant date, like 2007-2-14
5114 time The time, like 15:00-16:50
5115 extra String with extra planning info
5116 priority-l The priority letter if any was given
5117 priority-n The computed numerical priority
5119 Time and date will only be given if a timestamp (or deadline/scheduled)
5120 lead to the selection of the item.
5122 A CSV list like this is very easy to use in a post processing script.
5123 For example, here is a Perl program that gets the TODO list from
5124 Emacs/org-mode and prints all the items, preceded by a checkbox:
5128 # define the Emacs command to run
5129 $cmd = "emacs -batch -l ~/.emacs -eval '(org-batch-agenda-csv \"t\")'";
5131 # run it and capture the output
5132 $agenda = qx{$cmd 2>/dev/null};
5134 # loop over all lines
5135 foreach $line (split(/\n/,$agenda)) {
5137 # get the individual values
5138 ($category,$head,$type,$todo,$tags,$date,$time,$extra,
5139 $priority_l,$priority_n) = split(/,/,$line);
5141 # proccess and print
5142 print "[ ] $head\n";
5146 File: org, Node: Embedded LaTeX, Next: Exporting, Prev: Agenda views, Up: Top
5151 Plain ASCII is normally sufficient for almost all note taking. One
5152 exception, however, are scientific notes which need to be able to
5153 contain mathematical symbols and the occasional formula. LaTeX(1) is
5154 widely used to typeset scientific documents. Org-mode supports
5155 embedding LaTeX code into its files, because many academics are used to
5156 read LaTeX source code, and because it can be readily processed into
5157 images for HTML production.
5159 It is not necessary to mark LaTeX macros and code in any special way.
5160 If you observe a few conventions, Org-mode knows how to find it and what
5165 * Math symbols:: TeX macros for symbols and Greek letters
5166 * Subscripts and Superscripts:: Simple syntax for raising/lowering text
5167 * LaTeX fragments:: Complex formulas made easy
5168 * Processing LaTeX fragments:: Previewing LaTeX processing
5169 * CDLaTeX mode:: Speed up entering of formulas
5171 ---------- Footnotes ----------
5173 (1) LaTeX is a macro system based on Donald E. Knuth's TeX system.
5174 Many of the features described here as "LaTeX" are really from TeX, but
5175 for simplicity I am blurring this distinction.
5178 File: org, Node: Math symbols, Next: Subscripts and Superscripts, Prev: Embedded LaTeX, Up: Embedded LaTeX
5183 You can use LaTeX macros to insert special symbols like `\alpha' to
5184 indicate the Greek letter, or `\to' to indicate an arrow. Completion
5185 for these macros is available, just type `\' and maybe a few letters,
5186 and press `M-<TAB>' to see possible completions. Unlike LaTeX code,
5187 Org-mode allows these macros to be present without surrounding math
5188 delimiters, for example:
5190 Angles are written as Greek letters \alpha, \beta and \gamma.
5192 During HTML export (*note HTML export::), these symbols are
5193 translated into the proper syntax for HTML, for the above examples this
5194 is `α' and `→', respectively.
5197 File: org, Node: Subscripts and Superscripts, Next: LaTeX fragments, Prev: Math symbols, Up: Embedded LaTeX
5199 11.2 Subscripts and Superscripts
5200 ================================
5202 Just like in LaTeX, `^' and `_' are used to indicate super- and
5203 subscripts. Again, these can be used without embedding them in
5204 math-mode delimiters. To increase the readability of ASCII text, it is
5205 not necessary (but OK) to surround multi-character sub- and superscripts
5206 with curly braces. For example
5208 The mass if the sun is M_sun = 1.989 x 10^30 kg. The radius of
5209 the sun is R_{sun} = 6.96 x 10^8 m.
5211 To avoid interpretation as raised or lowered text, you can quote `^'
5212 and `_' with a backslash: `\_' and `\^'.
5214 During HTML export (*note HTML export::), subscript and superscripts
5215 are surrounded with `<sub>' and `<sup>' tags, respectively.
5218 File: org, Node: LaTeX fragments, Next: Processing LaTeX fragments, Prev: Subscripts and Superscripts, Up: Embedded LaTeX
5220 11.3 LaTeX fragments
5221 ====================
5223 With symbols, sub- and superscripts, HTML is pretty much at its end when
5224 it comes to representing mathematical formulas(1). More complex
5225 expressions need a dedicated formula processor. To this end, Org-mode
5226 can contain arbitrary LaTeX fragments. It provides commands to preview
5227 the typeset result of these fragments, and upon export to HTML, all
5228 fragments will be converted to images and inlined into the HTML
5229 document(2). For this to work you need to be on a system with a working
5230 LaTeX installation. You also need the `dvipng' program, available at
5231 `http://sourceforge.net/projects/dvipng/'. The LaTeX header that will
5232 be used when processing a fragment can be configured with the variable
5233 `org-format-latex-header'.
5235 LaTeX fragments don't need any special marking at all. The following
5236 snippets will be identified as LaTeX source code:
5237 * Environments of any kind. The only requirement is that the
5238 `\begin' statement appears on a new line, preceded by only
5241 * Text within the usual LaTeX math delimiters. To avoid conflicts
5242 with currency specifications, single `$' characters are only
5243 recognized as math delimiters if the enclosed text contains at
5244 most two line breaks, is directly attached to the `$' characters
5245 with no whitespace in between, and if the closing `$' is followed
5246 by whitespace or punctuation. For the other delimiters, there is
5247 no such restriction, so when in doubt, use `\(...\)' as inline
5252 \begin{equation} % arbitrary environments,
5253 x=\sqrt{b} % even tables, figures
5254 \end{equation} % etc
5256 If $a^2=b$ and \( b=2 \), then the solution must be
5257 either $$ a=+\sqrt{2} $$ or \[ a=-\sqrt{2} \].
5259 If you need any of the delimiter ASCII sequences for other purposes, you
5260 can configure the option `org-format-latex-options' to deselect the
5261 ones you do not wish to have interpreted by the LaTeX converter.
5263 ---------- Footnotes ----------
5265 (1) Yes, there is MathML, but that is not yet fully supported by
5266 many browsers, and there is no decent converter for turning LaTeX or
5267 ASCII representations of formulas into MathML. So for the time being,
5268 converting formulas into images seems the way to go.
5270 (2) The LaTeX export will not use images for displaying LaTeX
5271 fragments but include these fragments directly into the LaTeX code.
5274 File: org, Node: Processing LaTeX fragments, Next: CDLaTeX mode, Prev: LaTeX fragments, Up: Embedded LaTeX
5276 11.4 Processing LaTeX fragments
5277 ===============================
5279 LaTeX fragments can be processed to produce a preview images of the
5280 typeset expressions:
5283 Produce a preview image of the LaTeX fragment at point and overlay
5284 it over the source code. If there is no fragment at point,
5285 process all fragments in the current entry (between two
5286 headlines). When called with a prefix argument, process the
5287 entire subtree. When called with two prefix arguments, or when
5288 the cursor is before the first headline, process the entire buffer.
5291 Remove the overlay preview images.
5293 During HTML export (*note HTML export::), all LaTeX fragments are
5294 converted into images and inlined into the document if the following
5297 (setq org-export-with-LaTeX-fragments t)
5300 File: org, Node: CDLaTeX mode, Prev: Processing LaTeX fragments, Up: Embedded LaTeX
5302 11.5 Using CDLaTeX to enter math
5303 ================================
5305 CDLaTeX-mode is a minor mode that is normally used in combination with a
5306 major LaTeX mode like AUCTeX in order to speed-up insertion of
5307 environments and math templates. Inside Org-mode, you can make use of
5308 some of the features of cdlatex-mode. You need to install `cdlatex.el'
5309 and `texmathp.el' (the latter comes also with AUCTeX) from
5310 `http://www.astro.uva.nl/~dominik/Tools/cdlatex'. Don't turn
5311 cdlatex-mode itself under Org-mode, but use the light version
5312 `org-cdlatex-mode' that comes as part of Org-mode. Turn it on for the
5313 current buffer with `M-x org-cdlatex-mode', or for all Org-mode files
5316 (add-hook 'org-mode-hook 'turn-on-org-cdlatex)
5318 When this mode is enabled, the following features are present (for
5319 more details see the documentation of cdlatex-mode):
5320 * Environment templates can be inserted with `C-c {'.
5322 * The <TAB> key will do template expansion if the cursor is inside a
5323 LaTeX fragment(1). For example, <TAB> will expand `fr' to
5324 `\frac{}{}' and position the cursor correctly inside the first
5325 brace. Another <TAB> will get you into the second brace. Even
5326 outside fragments, <TAB> will expand environment abbreviations at
5327 the beginning of a line. For example, if you write `equ' at the
5328 beginning of a line and press <TAB>, this abbreviation will be
5329 expanded to an `equation' environment. To get a list of all
5330 abbreviations, type `M-x cdlatex-command-help'.
5332 * Pressing `_' and `^' inside a LaTeX fragment will insert these
5333 characters together with a pair of braces. If you use <TAB> to
5334 move out of the braces, and if the braces surround only a single
5335 character or macro, they are removed again (depending on the
5336 variable `cdlatex-simplify-sub-super-scripts').
5338 * Pressing the backquote ``' followed by a character inserts math
5339 macros, also outside LaTeX fragments. If you wait more than 1.5
5340 seconds after the backquote, a help window will pop up.
5342 * Pressing the normal quote `'' followed by another character
5343 modifies the symbol before point with an accent or a font. If you
5344 wait more than 1.5 seconds after the backquote, a help window will
5345 pop up. Character modification will work only inside LaTeX
5346 fragments, outside the quote is normal.
5348 ---------- Footnotes ----------
5350 (1) Org-mode has a method to test if the cursor is inside such a
5351 fragment, see the documentation of the function
5352 `org-inside-LaTeX-fragment-p'.
5355 File: org, Node: Exporting, Next: Publishing, Prev: Embedded LaTeX, Up: Top
5360 Org-mode documents can be exported into a variety of other formats. For
5361 printing and sharing of notes, ASCII export produces a readable and
5362 simple version of an Org-mode file. HTML export allows you to publish a
5363 notes file on the web, while the XOXO format provides a solid base for
5364 exchange with a broad range of other applications. LaTeX export lets
5365 you use Org-mode and its structured editing functions to easily create
5366 LaTeX files. To incorporate entries with associated times like
5367 deadlines or appointments into a desktop calendar program like iCal,
5368 Org-mode can also produce extracts in the iCalendar format. Currently
5369 Org-mode only supports export, not import of these different formats.
5371 When exporting, Org-mode uses special conventions to enrich the
5372 output produced. *Note Text interpretation::, for more details.
5375 Dispatcher for export and publishing commands. Displays a
5376 help-window listing the additional key(s) needed to launch an
5377 export or publishing command.
5381 * ASCII export:: Exporting to plain ASCII
5382 * HTML export:: Exporting to HTML
5383 * LaTeX export:: Exporting to LaTeX
5384 * XOXO export:: Exporting to XOXO
5385 * iCalendar export:: Exporting in iCalendar format
5386 * Text interpretation:: How the exporter looks at the file
5389 File: org, Node: ASCII export, Next: HTML export, Prev: Exporting, Up: Exporting
5394 ASCII export produces a simple and very readable version of an Org-mode
5398 Export as ASCII file. For an org file `myfile.org', the ASCII file
5399 will be `myfile.txt'. The file will be overwritten without
5400 warning. If there is an active region, only the region will be
5401 exported. If the selected region is a single tree, the tree head
5402 will become the document title. If the tree head entry has or
5403 inherits an EXPORT_FILE_NAME property, that name will be used for
5407 Export only the visible part of the document.
5409 In the exported version, the first 3 outline levels will become
5410 headlines, defining a general document structure. Additional levels
5411 will be exported as itemized lists. If you want that transition to
5412 occur at a different level, specify it with a prefix argument. For
5417 creates only top level headlines and does the rest as items. When
5418 headlines are converted to items, the indentation of the text following
5419 the headline is changed to fit nicely under the item. This is done with
5420 the assumption that the first bodyline indicates the base indentation of
5421 the body text. Any indentation larger than this is adjusted to preserve
5422 the layout relative to the first line. Should there be lines with less
5423 indentation than the first, these are left alone.
5426 File: org, Node: HTML export, Next: LaTeX export, Prev: ASCII export, Up: Exporting
5431 Org-mode contains an HTML (XHTML 1.0 strict) exporter with extensive
5432 HTML formatting, in ways similar to John Grubers _markdown_ language,
5433 but with additional support for tables.
5437 * HTML Export commands:: How to invoke LaTeX export
5438 * Quoting HTML tags:: Using direct HTML in Org-mode
5439 * Links:: Transformation of links for HTML
5440 * Images:: How to include images
5441 * CSS support:: Changing the appearence of the output
5444 File: org, Node: HTML Export commands, Next: Quoting HTML tags, Prev: HTML export, Up: HTML export
5446 12.2.1 HTML export commands
5447 ---------------------------
5450 Export as HTML file `myfile.html'. For an org file `myfile.org',
5451 the ASCII file will be `myfile.html'. The file will be
5452 overwritten without warning. If there is an active region, only
5453 the region will be exported. If the selected region is a single
5454 tree, the tree head will become the document title. If the tree
5455 head entry has or inherits an EXPORT_FILE_NAME property, that name
5456 will be used for the export.
5459 Export as HTML file and immediately open it with a browser.
5462 Export to a temporary buffer, do not create a file.
5465 Export the active region to a temporary buffer. With prefix arg,
5466 do not produce file header and foot, but just the plain HTML
5467 section for the region. This is good for cut-and-paste operations.
5476 Export only the visible part of the document.
5478 `M-x org-export-region-as-html'
5479 Convert the region to HTML under the assumption that it was
5480 org-mode syntax before. This is a global command that can be
5481 invoked in any buffer.
5483 `M-x org-replace-region-by-HTML'
5484 Replace the active region (assumed to be in Org-mode syntax) by
5487 In the exported version, the first 3 outline levels will become
5488 headlines, defining a general document structure. Additional levels
5489 will be exported as itemized lists. If you want that transition to
5490 occur at a different level, specify it with a prefix argument. For
5495 creates two levels of headings and does the rest as items.
5498 File: org, Node: Quoting HTML tags, Next: Links, Prev: HTML Export commands, Up: HTML export
5500 12.2.2 Quoting HTML tags
5501 ------------------------
5503 Plain `<' and `>' are always transformed to `<' and `>' in HTML
5504 export. If you want to include simple HTML tags which should be
5505 interpreted as such, mark them with `@' as in `@<b>bold text@</b>'.
5506 Note that this really works only for simple tags. For more extensive
5507 HTML that should be copied verbatim to the exported file use either
5509 #+HTML: Literal HTML code for export
5514 All lines between these markers are exported literally
5518 File: org, Node: Links, Next: Images, Prev: Quoting HTML tags, Up: HTML export
5523 Internal links (*note Internal links::) will continue to work in HTML
5524 files only if they match a dedicated `<<target>>'. Automatic links
5525 created by radio targets (*note Radio targets::) will also work in the
5526 HTML file. Links to external files will still work if the HTML file is
5527 in the same directory as the Org-mode file. Links to other `.org'
5528 files will be translated into HTML links under the assumption that an
5529 HTML version also exists of the linked file. For information related to
5530 linking files while publishing them to a publishing directory see *Note
5534 File: org, Node: Images, Next: CSS support, Prev: Links, Up: HTML export
5539 HTML export can inline images given as links in the Org-mode file, and
5540 it can make an image the clickable part of a link. By default(1),
5541 images are inlined if a link does not have a description. So
5542 `[[file:myimg.jpg]]' will be inlined, while `[[file:myimg.jpg][the
5543 image]]' will just produce a link `the image' that points to the image.
5544 If the description part itself is a `file:' link or a `http:' URL
5545 pointing to an image, this image will be inlined and activated so that
5546 clicking on the image will activate the link. For example, to include
5547 a thumbnail that will link to a high resolution version of the image,
5550 [[file:highres.jpg][file:thumb.jpg]]
5552 and you could use `http' addresses just as well.
5554 ---------- Footnotes ----------
5556 (1) but see the variable `org-export-html-inline-images'
5559 File: org, Node: CSS support, Prev: Images, Up: HTML export
5564 You can also give style information for the exported file. The HTML
5565 exporter assigns the following CSS classes to appropriate parts of the
5566 document - your style specifications may change these:
5568 .done the DONE keyword
5569 .timestamp time stamp
5570 .timestamp-kwd keyword associated with a time stamp, like SCHEDULED
5571 .tag tag in a headline
5572 .target target for links
5574 The default style specification can be configured through the option
5575 `org-export-html-style'. If you want to use a file-local style, you
5576 may use file variables, best wrapped into a COMMENT section at the end
5577 of the outline tree. For example(1):
5579 * COMMENT html style specifications
5582 # org-export-html-style: " <style type=\"text/css\">
5583 # p {font-weight: normal; color: gray; }
5584 # h1 {color: black; }
5588 Remember to execute `M-x normal-mode' after changing this to make
5589 the new style visible to Emacs. This command restarts org-mode for the
5590 current buffer and forces Emacs to re-evaluate the local variables
5591 section in the buffer.
5593 ---------- Footnotes ----------
5595 (1) Under Emacs 21, the continuation lines for a variable value
5596 should have no `#' at the start of the line.
5599 File: org, Node: LaTeX export, Next: XOXO export, Prev: HTML export, Up: Exporting
5604 Org-mode contains a LaTeX exporter written by Bastien Guerry.
5608 * LaTeX export commands:: How to invoke LaTeX export
5609 * Quoting LaTeX code:: Incorporating literal LaTeX code
5612 File: org, Node: LaTeX export commands, Next: Quoting LaTeX code, Prev: LaTeX export, Up: LaTeX export
5614 12.3.1 LaTeX export commands
5615 ----------------------------
5618 Export as LaTeX file `myfile.tex'.
5621 Export to a temporary buffer, do not create a file.
5626 Export only the visible part of the document.
5628 `M-x org-export-region-as-latex'
5629 Convert the region to LaTeX under the assumption that it was
5630 org-mode syntax before. This is a global command that can be
5631 invoked in any buffer.
5633 `M-x org-replace-region-by-latex'
5634 Replace the active region (assumed to be in Org-mode syntax) by
5637 In the exported version, the first 3 outline levels will become
5638 headlines, defining a general document structure. Additional levels
5639 will be exported as description lists. The exporter can ignore them or
5640 convert them to a custom string depending on `org-latex-low-levels'.
5642 If you want that transition to occur at a different level, specify it
5643 with a prefix argument. For example,
5647 creates two levels of headings and does the rest as items.
5650 File: org, Node: Quoting LaTeX code, Prev: LaTeX export commands, Up: LaTeX export
5652 12.3.2 Quoting LaTeX code
5653 -------------------------
5655 Embedded LaTeX as described in *Note Embedded LaTeX:: will be correctly
5656 inserted into the LaTeX file. Forthermore, you can add special code
5657 that should only be present in LaTeX export with the following
5660 #+LaTeX: Literal LaTeX code for export
5665 All lines between these markers are exported literally
5669 File: org, Node: XOXO export, Next: iCalendar export, Prev: LaTeX export, Up: Exporting
5674 Org-mode contains an exporter that produces XOXO-style output.
5675 Currently, this exporter only handles the general outline structure and
5676 does not interpret any additional Org-mode features.
5679 Export as XOXO file `myfile.html'.
5682 Export only the visible part of the document.
5685 File: org, Node: iCalendar export, Next: Text interpretation, Prev: XOXO export, Up: Exporting
5687 12.5 iCalendar export
5688 =====================
5690 Some people like to use Org-mode for keeping track of projects, but
5691 still prefer a standard calendar application for anniversaries and
5692 appointments. In this case it can be useful to have deadlines and
5693 other time-stamped items in Org-mode files show up in the calendar
5694 application. Org-mode can export calendar information in the standard
5695 iCalendar format. If you also want to have TODO entries included in the
5696 export, configure the variable `org-icalendar-include-todo'.
5699 Create iCalendar entries for the current file and store them in
5700 the same directory, using a file extension `.ics'.
5703 Like `C-c C-e i', but do this for all files in `org-agenda-files'.
5704 For each of these files, a separate iCalendar file will be
5708 Create a single large iCalendar file from all files in
5709 `org-agenda-files' and write it to the file given by
5710 `org-combined-agenda-icalendar-file'.
5712 The export will honor SUMMARY, DESCRIPTION and LOCATION properties if
5713 the selected entries have them. If not, the summary will be derived
5714 from the headline, and the description from the body (limited to
5715 `org-icalendar-include-body' characters).
5717 How this calendar is best read and updated, depends on the
5718 application you are using. The FAQ covers this issue.
5721 File: org, Node: Text interpretation, Prev: iCalendar export, Up: Exporting
5723 12.6 Text interpretation by the exporter
5724 ========================================
5726 The exporter backends interpret additional structure in the Org-mode
5727 file in order to produce better output.
5731 * Comment lines:: Some lines will not be exported
5732 * Initial text:: Text before the first headline
5733 * Footnotes:: Numbers like [1]
5734 * Enhancing text:: Subscripts, symbols and more
5735 * Export options:: How to influence the export settings
5738 File: org, Node: Comment lines, Next: Initial text, Prev: Text interpretation, Up: Text interpretation
5740 12.6.1 Comment lines
5741 --------------------
5743 Lines starting with `#' in column zero are treated as comments and will
5744 never be exported. Also entire subtrees starting with the word
5745 `COMMENT' will never be exported.
5748 Toggle the COMMENT keyword at the beginning of an entry.
5751 File: org, Node: Initial text, Next: Footnotes, Prev: Comment lines, Up: Text interpretation
5753 12.6.2 Text before the first headline
5754 -------------------------------------
5756 Org-mode normally ignores any text before the first headline when
5757 exporting, leaving this region for internal links to speed up navigation
5758 etc. However, in publishing-oriented files, you might want to have some
5759 text before the first headline, like a small introduction, special HTML
5760 code with a navigation bar, etc. You can ask to have this part of the
5761 file exported as well by setting the variable
5762 `org-export-skip-text-before-1st-heading' to `nil'. On a per-file
5763 basis, you can get the same effect with
5767 The text before the first headline will be fully processed (*note
5768 Enhancing text::), and the first non-comment line becomes the title of
5769 the exported document. If you need to include literal HTML, use the
5770 special constructs described in *Note Quoting HTML tags::. The table
5771 of contents is normally inserted directly before the first headline of
5772 the file. If you would like to get it to a different location, insert
5773 the string `[TABLE-OF-CONTENTS]' on a line by itself at the desired
5776 Finally, if you want to use the space before the first headline for
5777 internal purposes, but _still_ want to place something before the first
5778 headline when exporting the file, you can use the `#+TEXT' construct:
5781 #+TEXT: This text will go before the *first* headline.
5782 #+TEXT: We place the table of contents here:
5783 #+TEXT: [TABLE-OF-CONTENTS]
5784 #+TEXT: This goes between the table of contents and the first headline
5787 File: org, Node: Footnotes, Next: Enhancing text, Prev: Initial text, Up: Text interpretation
5792 Numbers in square brackets are treated as footnotes, so that you can use
5793 the Emacs package `footnote.el' to create footnotes. For example:
5795 The org-mode homepage[1] clearly needs help from
5796 a good web designer.
5798 [1] The link is: http://orgmode.org
5800 Note that the `footnote' package uses `C-c !' to invoke its commands.
5801 This binding conflicts with the org-mode command for inserting inactive
5802 time stamps. You could use the variable `footnote-prefix' to switch
5803 footnotes commands to another key. Or, if you are too used to this
5804 binding, you could use `org-replace-disputed-keys' and
5805 `org-disputed-keys' to change the settings in Org-mode.
5808 File: org, Node: Enhancing text, Next: Export options, Prev: Footnotes, Up: Text interpretation
5810 12.6.4 Enhancing text for export
5811 --------------------------------
5813 Some of the export backends of Org-mode allow for sophisticated text
5814 formatting, this is true in particular for the HTML and LaTeX backends.
5815 Org-mode has a number of typing conventions that allow to produce a
5816 richly formatted output.
5818 * Plain lists `-', `*' or `+' as bullet, or with `1.' or `2)' as
5819 enumerator will be recognized and transformed if the backend
5820 supports lists. See *Note Plain lists::.
5822 * You can make words *bold*, /italic/, _underlined_, `=code=', and
5823 even `+strikethrough+'(1).
5825 * A line consisting of only dashes, and at least 5 of them, will be
5826 exported as a horizontal line (`<hr/>' in HTML).
5828 * Many TeX macros and entire LaTeX fragments are converted into HTML
5829 entities or images (*note Embedded LaTeX::).
5831 * Tables are transformed into native tables under the exporter, if
5832 the export backend supports this. Data fields before the first
5833 horizontal separator line will be formatted as table header fields.
5835 * If a headline starts with the word `QUOTE', the text below the
5836 headline will be typeset as fixed-width, to allow quoting of
5837 computer codes etc. Lines starting with `:' are also typeset in
5840 Toggle fixed-width for entry (QUOTE) or region, see below.
5842 * A double backslash _at the end of a line_ enforces a line break at
5845 If these conversions conflict with your habits of typing ASCII text,
5846 they can all be turned off with corresponding variables. See the
5847 customization group `org-export-general', and the following section
5848 which explains how to set export options with special lines in a buffer.
5850 ---------- Footnotes ----------
5852 (1) but remember that strikethrough is typographically evil and
5853 should never be used.
5856 File: org, Node: Export options, Prev: Enhancing text, Up: Text interpretation
5858 12.6.5 Export options
5859 ---------------------
5861 The exporter recognizes special lines in the buffer which provide
5862 additional information. These lines may be put anywhere in the file.
5863 The whole set of lines can be inserted into the buffer with `C-c C-e
5864 t'. For individual lines, a good way to make sure the keyword is
5865 correct is to type `#+' and then use `M-<TAB>' completion (*note
5869 Insert template with export options, see example below.
5871 #+TITLE: the title to be shown (default is the buffer name)
5872 #+AUTHOR: the author (default taken from `user-full-name')
5873 #+DATE: A date, fixed, of a format string for `format-time-string'
5874 #+EMAIL: his/her email address (default from `user-mail-address')
5875 #+LANGUAGE: language for HTML, e.g. `en' (`org-export-default-language')
5876 #+TEXT: Some descriptive text to be inserted at the beginning.
5877 #+TEXT: Several lines may be given.
5878 #+OPTIONS: H:2 num:t toc:t \n:nil @:t ::t |:t ^:t f:t TeX:t ...
5880 The OPTIONS line is a compact form to specify export settings. Here
5882 H: set the number of headline levels for export
5883 num: turn on/off section-numbers
5884 toc: turn on/off table of contents, or set level limit (integer)
5885 \n: turn on/off linebreak-preservation
5886 @: turn on/off quoted HTML tags
5887 :: turn on/off fixed-width sections
5888 |: turn on/off tables
5889 ^: turn on/off TeX-like syntax for sub- and superscripts. If
5890 you write "^:{}", `a_{b}' will be interpreted, but
5891 the simple `a_b' will be left as it is.
5892 f: turn on/off foototes like this[1].
5893 *: turn on/off emphasized text (bold, italic, underlined)
5894 TeX: turn on/off simple TeX macros in plain text
5895 LaTeX: turn on/off LaTeX fragments
5896 skip: turn on/off skipping the text before the first heading
5897 author: turn on/off inclusion of author name/email into exported file
5898 timestamp: turn on/off inclusion creation time into exported file
5899 p: turn on/off inclusion of tags
5901 These options take effect in both the HTML and LaTeX export, except
5902 for `TeX' and `LaTeX', which are respectively `t' and `nil' for the
5906 File: org, Node: Publishing, Next: Miscellaneous, Prev: Exporting, Up: Top
5911 Org-mode includes(1) a publishing management system that allows you to
5912 configure automatic HTML conversion of _projects_ composed of
5913 interlinked org files. This system is called _org-publish_. You can
5914 also configure org-publish to automatically upload your exported HTML
5915 pages and related attachments, such as images and source code files, to
5916 a web server. Org-publish turns org-mode into a web-site authoring tool.
5918 You can also use Org-publish to convert files into LaTeX, or even
5919 combine HTML and LaTeX conversion so that files are available in both
5920 formats on the server(2).
5922 Org-publish has been contributed to Org-mode by David O'Toole.
5926 * Configuration:: Defining projects
5927 * Sample configuration:: Example projects
5928 * Triggering publication:: Publication commands
5930 ---------- Footnotes ----------
5932 (1) `org-publish.el' is not distributed with Emacs 21, if you are
5933 still using Emacs 21, you need you need to download this file
5936 (2) Since LaTeX files on a server are not that helpful, you surely
5937 want to perform further conversion on them - e.g. convert them to `PDF'
5941 File: org, Node: Configuration, Next: Sample configuration, Prev: Publishing, Up: Publishing
5946 Publishing needs significant configuration to specify files, destination
5947 and many other properties of a project.
5951 * Project alist:: The central configuration variable
5952 * Sources and destinations:: From here to there
5953 * Selecting files:: What files are part of the project?
5954 * Publishing action:: Setting the function doing the publishing
5955 * Publishing options:: Tweaking HTML export
5956 * Publishing links:: Which links keep working after publishing?
5957 * Project page index:: Publishing a list of project files
5960 File: org, Node: Project alist, Next: Sources and destinations, Prev: Configuration, Up: Configuration
5962 13.1.1 The variable `org-publish-project-alist'
5963 -----------------------------------------------
5965 Org-publish is configured almost entirely through setting the value of
5966 one variable, called `org-publish-project-alist'. Each element of the
5967 list configures one project, and may be in one of the two following
5970 ("project-name" :property value :property value ...)
5974 ("project-name" :components ("project-name" "project-name" ...))
5976 In both cases, projects are configured by specifying property values.
5977 A project defines the set of files that will be published, as well as
5978 the publishing configuration to use when publishing those files. When
5979 a project takes the second form listed above, the individual members of
5980 the "components" property are taken to be components of the project,
5981 which group together files requiring different publishing options. When
5982 you publish such a "meta-project" all the components will also publish.
5985 File: org, Node: Sources and destinations, Next: Selecting files, Prev: Project alist, Up: Configuration
5987 13.1.2 Sources and destinations for files
5988 -----------------------------------------
5990 Most properties are optional, but some should always be set. In
5991 particular, org-publish needs to know where to look for source files,
5992 and where to put published files.
5994 `:base-directory' Directory containing publishing source files
5995 `:publishing-directory'Directory (possibly remote) where output files
5997 `:preparation-function'Function called before starting publishing
5998 process, for example to run `make' for updating
5999 files to be published.
6002 File: org, Node: Selecting files, Next: Publishing action, Prev: Sources and destinations, Up: Configuration
6004 13.1.3 Selecting files
6005 ----------------------
6007 By default, all files with extension `.org' in the base directory are
6008 considered part of the project. This can be modified by setting the
6010 `:base-extension' Extension (without the dot!) of source files. This
6011 actually is a regular expression.
6012 `:exclude' Regular expression to match file names that should
6013 not be published, even though they have been selected
6014 on the basis of their extension.
6015 `:include' List of files to be included regardless of
6016 `:base-extension' and `:exclude'.
6019 File: org, Node: Publishing action, Next: Publishing options, Prev: Selecting files, Up: Configuration
6021 13.1.4 Publishing Action
6022 ------------------------
6024 Publishing means that a file is copied to the destination directory and
6025 possibly transformed in the process. The default transformation is to
6026 export Org-mode files as HTML files, and this is done by the function
6027 `org-publish-org-to-html' which calls the HTML exporter (*note HTML
6028 export::). But you also can publish your files in LaTeX by using the
6029 function `org-publish-org-to-latex' instead. Other files like images
6030 only need to be copied to the publishing destination. For non-Org-mode
6031 files, you need to specify the publishing function.
6033 `:publishing-function' Function executing the publication of a file.
6034 This may also be a list of functions, which will
6035 all be called in turn.
6037 The function must accept two arguments: a property list containing at
6038 least a `:publishing-directory' property, and the name of the file to
6039 be published. It should take the specified file, make the necessary
6040 transformation (if any) and place the result into the destination
6041 folder. You can write your own publishing function, but `org-publish'
6042 provides one for attachments (files that only need to be copied):
6043 `org-publish-attachment'.
6046 File: org, Node: Publishing options, Next: Publishing links, Prev: Publishing action, Up: Configuration
6048 13.1.5 Options for the HTML/LaTeX exporters
6049 -------------------------------------------
6051 The property list can be used to set many export options for the HTML
6052 and LaTeX exporters. In most cases, these properties correspond to user
6053 variables in Org-mode. The table below lists these properties along
6054 with the variable they belong to. See the documentation string for the
6055 respective variable for details.
6057 `:language' `org-export-default-language'
6058 `:headline-levels' `org-export-headline-levels'
6059 `:section-numbers' `org-export-with-section-numbers'
6060 `:table-of-contents' `org-export-with-toc'
6061 `:archived-trees' `org-export-with-archived-trees'
6062 `:emphasize' `org-export-with-emphasize'
6063 `:sub-superscript' `org-export-with-sub-superscripts'
6064 `:TeX-macros' `org-export-with-TeX-macros'
6065 `:LaTeX-fragments' `org-export-with-LaTeX-fragments'
6066 `:fixed-width' `org-export-with-fixed-width'
6067 `:timestamps' `org-export-with-timestamps'
6069 `:tags' `org-export-with-tags'
6071 `:tables' `org-export-with-tables'
6072 `:table-auto-headline' `org-export-highlight-first-table-line'
6073 `:style' `org-export-html-style'
6074 `:convert-org-links' `org-export-html-link-org-files-as-html'
6075 `:inline-images' `org-export-html-inline-images'
6076 `:expand-quoted-html' `org-export-html-expand'
6077 `:timestamp' `org-export-html-with-timestamp'
6078 `:publishing-directory'`org-export-publishing-directory'
6079 `:preamble' `org-export-html-preamble'
6080 `:postamble' `org-export-html-postamble'
6081 `:auto-preamble' `org-export-html-auto-preamble'
6082 `:auto-postamble' `org-export-html-auto-postamble'
6083 `:author' `user-full-name'
6084 `:email' `user-mail-address'
6086 Most of the `org-export-with-*' variables have the same effect in
6087 both HTML and LaTeX exporters, except for `:TeX-macros' and
6088 `:LaTeX-fragments', respectively `nil' and `t' in the LaTeX export.
6090 When a property is given a value in org-publish-project-alist, its
6091 setting overrides the value of the corresponding user variable (if any)
6092 during publishing. Options set within a file (*note Export options::),
6093 however, override everything.
6096 File: org, Node: Publishing links, Next: Project page index, Prev: Publishing options, Up: Configuration
6098 13.1.6 Links between published files
6099 ------------------------------------
6101 To create a link from one Org-mode file to another, you would use
6102 something like `[[file:foo.org][The foo]]' or simply `file:foo.org.'
6103 (*note Hyperlinks::). Upon publishing this link becomes a link to
6104 `foo.html'. In this way, you can interlink the pages of your "org web"
6105 project and the links will work as expected when you publish them to
6108 You may also link to related files, such as images. Provided you are
6109 careful with relative pathnames, and provided you have also configured
6110 org-publish to upload the related files, these links will work too.
6111 *Note Complex example:: for an example of this usage.
6113 Sometime an Org-mode file to be published may contain links that are
6114 only valid in your production environment, but not in the publishing
6115 location. In this case, use the property
6117 `:link-validation-function' Function to validate links
6119 to define a function for checking link validity. This function must
6120 accept two arguments, the file name and a directory relative to which
6121 the file name is interpreted in the production environment. If this
6122 function returns `nil', then the HTML generator will only insert a
6123 description into the HTML file, but no link. One option for this
6124 function is `org-publish-validate-link' which checks if the given file
6125 is part of any project in `org-publish-project-alist'.
6128 File: org, Node: Project page index, Prev: Publishing links, Up: Configuration
6130 13.1.7 Project page index
6131 -------------------------
6133 The following properties may be used to control publishing of an index
6134 of files or summary page for a given project.
6136 `:auto-index' When non-nil, publish an index during
6137 org-publish-current-project or org-publish-all.
6138 `:index-filename' Filename for output of index. Defaults to `index.org'
6139 (which becomes `index.html').
6140 `:index-title' Title of index page. Defaults to name of file.
6141 `:index-function' Plugin function to use for generation of index.
6142 Defaults to `org-publish-org-index', which generates
6143 a plain list of links to all files in the project.
6146 File: org, Node: Sample configuration, Next: Triggering publication, Prev: Configuration, Up: Publishing
6148 13.2 Sample configuration
6149 =========================
6151 Below we provide two example configurations. The first one is a simple
6152 project publishing only a set of Org-mode files. The second example is
6153 more complex, with a multi-component project.
6157 * Simple example:: One-component publishing
6158 * Complex example:: A multi-component publishing example
6161 File: org, Node: Simple example, Next: Complex example, Prev: Sample configuration, Up: Sample configuration
6163 13.2.1 Example: simple publishing configuration
6164 -----------------------------------------------
6166 This example publishes a set of Org-mode files to the `public_html'
6167 directory on the local machine.
6169 (setq org-publish-project-alist
6171 :base-directory "~/org/"
6172 :publishing-directory "~/public_html"
6173 :section-numbers nil
6174 :table-of-contents nil
6175 :style "<link rel=stylesheet
6176 href=\"../other/mystyle.css\"
6177 type=\"text/css\">")))
6180 File: org, Node: Complex example, Prev: Simple example, Up: Sample configuration
6182 13.2.2 Example: complex publishing configuration
6183 ------------------------------------------------
6185 This more complicated example publishes an entire website, including
6186 org files converted to HTML, image files, emacs lisp source code, and
6187 stylesheets. The publishing-directory is remote and private files are
6190 To ensure that links are preserved, care should be taken to replicate
6191 your directory structure on the web server, and to use relative file
6192 paths. For example, if your org files are kept in `~/org' and your
6193 publishable images in `~/images', you'd link to an image with
6194 file:../images/myimage.png
6195 On the web server, the relative path to the image should be the
6196 same. You can accomplish this by setting up an "images" folder in the
6197 right place on the webserver, and publishing images to it.
6199 (setq org-publish-project-alist
6201 :base-directory "~/org/"
6202 :base-extension "org"
6203 :publishing-directory "/ssh:user@host:~/html/notebook/"
6204 :publishing-function org-publish-org-to-html
6205 :exclude "PrivatePage.org" ;; regexp
6207 :section-numbers nil
6208 :table-of-contents nil
6209 :style "<link rel=stylesheet
6210 href=\"../other/mystyle.css\" type=\"text/css\">"
6212 :auto-postamble nil)
6215 :base-directory "~/images/"
6216 :base-extension "jpg\\|gif\\|png"
6217 :publishing-directory "/ssh:user@host:~/html/images/"
6218 :publishing-function org-publish-attachment)
6221 :base-directory "~/other/"
6222 :base-extension "css\\|el"
6223 :publishing-directory "/ssh:user@host:~/html/other/"
6224 :publishing-function org-publish-attachment)
6225 ("website" :components ("orgfiles" "images" "other"))))
6228 File: org, Node: Triggering publication, Prev: Sample configuration, Up: Publishing
6230 13.3 Triggering publication
6231 ===========================
6233 Once org-publish is properly configured, you can publish with the
6234 following functions:
6237 Prompt for a specific project and publish all files that belong to
6241 Publish the project containing the current file.
6244 Publish only the current file.
6247 Publish all projects.
6249 Org uses timestamps to track when a file has changed. The above
6250 functions normally only publish changed files. You can override this and
6251 force publishing of all files by giving a prefix argument.
6254 File: org, Node: Miscellaneous, Next: Extensions and Hacking, Prev: Publishing, Up: Top
6261 * Completion:: M-TAB knows what you need
6262 * Customization:: Adapting Org-mode to your taste
6263 * In-buffer settings:: Overview of the #+KEYWORDS
6264 * The very busy C-c C-c key:: When in doubt, press C-c C-c
6265 * Clean view:: Getting rid of leading stars in the outline
6266 * TTY keys:: Using Org-mode on a tty
6267 * Interaction:: Other Emacs packages
6268 * Bugs:: Things which do not work perfectly
6271 File: org, Node: Completion, Next: Customization, Prev: Miscellaneous, Up: Miscellaneous
6276 Org-mode supports in-buffer completion. This type of completion does
6277 not make use of the minibuffer. You simply type a few letters into the
6278 buffer and use the key to complete text right there.
6281 Complete word at point
6282 * At the beginning of a headline, complete TODO keywords.
6284 * After `\', complete TeX symbols supported by the exporter.
6286 * After `*', complete headlines in the current buffer so that
6287 they can be used in search links like `[[*find this
6290 * After `:' in a headline, complete tags. The list of tags is
6291 taken from the variable `org-tag-alist' (possibly set through
6292 the `#+TAGS' in-buffer option, *note Setting tags::), or it
6293 is created dynamically from all tags used in the current
6296 * After `:' and not in a headline, complete property keys. The
6297 list of keys is constructed dynamically from all keys used in
6300 * After `[', complete link abbreviations (*note Link
6303 * After `#+', complete the special keywords like `TYP_TODO' or
6304 `OPTIONS' which set file-specific options for Org-mode. When
6305 the option keyword is already complete, pressing `M-<TAB>'
6306 again will insert example settings for this keyword.
6308 * In the line after `#+STARTUP: ', complete startup keywords,
6309 i.e. valid keys for this line.
6311 * Elsewhere, complete dictionary words using ispell.
6314 File: org, Node: Customization, Next: In-buffer settings, Prev: Completion, Up: Miscellaneous
6319 There are more than 180 variables that can be used to customize
6320 Org-mode. For the sake of compactness of the manual, I am not
6321 describing the variables here. A structured overview of customization
6322 variables is available with `M-x org-customize'. Or select `Browse Org
6323 Group' from the `Org->Customization' menu. Many settings can also be
6324 activated on a per-file basis, by putting special lines into the buffer
6325 (*note In-buffer settings::).
6328 File: org, Node: In-buffer settings, Next: The very busy C-c C-c key, Prev: Customization, Up: Miscellaneous
6330 14.3 Summary of in-buffer settings
6331 ==================================
6333 Org-mode uses special lines in the buffer to define settings on a
6334 per-file basis. These lines start with a `#+' followed by a keyword, a
6335 colon, and then individual words defining a setting. Several setting
6336 words can be in the same line, but you can also have multiple lines for
6337 the keyword. While these settings are described throughout the manual,
6338 here is a summary. After changing any of those lines in the buffer,
6339 press `C-c C-c' with the cursor still in the line to activate the
6340 changes immediately. Otherwise they become effective only when the
6341 file is visited again in a new Emacs session.
6343 `#+ARCHIVE: %s_done::'
6344 This line sets the archive location for the agenda file. It
6345 applies for all subsequent lines until the next `#+ARCHIVE' line,
6346 or the end of the file. The first such line also applies to any
6347 entries before it. The corresponding variable is
6348 `org-archive-location'.
6351 This line sets the category for the agenda file. The category
6352 applies for all subsequent lines until the next `#+CATEGORY' line,
6353 or the end of the file. The first such line also applies to any
6356 `#+COLUMNS: %25ITEM .....'
6357 Set the default format for columns view. This format applies when
6358 columns view is invoked in location where no COLUMNS property
6361 `#+CONSTANTS: name1=value1 ...'
6362 Set file-local values for constants to be used in table formulas.
6363 This line set the local variable
6364 `org-table-formula-constants-local'. The global version of theis
6365 variable is `org-table-formula-constants'. corresponding
6367 `#+LINK: linkword replace'
6368 These lines (several are allowed) specify link abbreviations.
6369 *Note Link abbreviations::. The corresponding variable is
6370 `org-link-abbrev-alist'.
6372 `#+PRIORITIES: highest lowest default'
6373 This line sets the limits and the default for the priorities. All
6374 three must be either letters A-Z or numbers 0-9. The highest
6375 priority must have a lower ASCII number that the lowest priority.
6377 `#+PROPERTY: Property_Name Value'
6378 This line sets a default inheritance value for entries in the
6379 current buffer, most useful for specifying the allowed values of a
6383 This line sets options to be used at startup of Org-mode, when an
6384 Org-mode file is being visited. The first set of options deals
6385 with the initial visibility of the outline tree. The
6386 corresponding variable for global default settings is
6387 `org-startup-folded', with a default value `t', which means
6389 overview top-level headlines only
6390 content all headlines
6391 showall no folding at all, show everything
6392 Then there are options for aligning tables upon visiting a file.
6393 This is useful in files containing narrowed table columns. The
6394 corresponding variable is `org-startup-align-all-tables', with a
6395 default value `nil'.
6396 align align all tables
6397 noalign don't align tables on startup
6398 Logging TODO state changes and clock intervals (variables
6399 `org-log-done' and `org-log-repeat') can be configured using these
6401 logging record a timestamp when an item is marked DONE
6402 nologging don't record when items are marked DONE
6403 lognotedone record timestamp and a note when DONE
6404 lognotestate record timestamp and a note when TODO state changes
6405 logrepeat record a note when re-instating a repeating item
6406 nologrepeat do not record when re-instating repeating item
6407 lognoteclock-out record timestamp and a note when clocking out
6408 Here are the options for hiding leading stars in outline headings.
6409 The corresponding variables are `org-hide-leading-stars' and
6410 `org-odd-levels-only', both with a default setting `nil' (meaning
6411 `showstars' and `oddeven').
6412 hidestars make all but one of the stars starting a headline invisible.
6413 showstars show all stars starting a headline
6414 odd allow only odd outline levels (1,3,...)
6415 oddeven allow all outline levels
6416 To turn on custom format overlays over time stamps (variables
6417 `org-put-time-stamp-overlays' and
6418 `org-time-stamp-overlay-formats'), use
6419 customtime overlay custom time format
6420 The following options influence the table spreadsheet (variable
6421 `constants-unit-system').
6422 constcgs `constants.el' should use the c-g-s unit system
6423 constSI `constants.el' should use the SI unit system
6425 `#+TAGS: TAG1(c1) TAG2(c2)'
6426 These lines (several such lines are allowed) specify the legal
6427 tags in this file, and (potentially) the corresponding _fast tag
6428 selection_ keys. The corresponding variable is `org-tag-alist'.
6431 This line contains the formulas for the table directly above the
6434 `#+TITLE:, #+AUTHOR:, #+EMAIL:, #+LANGUAGE:, #+TEXT:, #+OPTIONS, #+DATE:'
6435 These lines provide settings for exporting files. For more
6436 details see *Note Export options::.
6438 `#+SEQ_TODO: #+TYP_TODO:'
6439 These lines set the TODO keywords and their interpretation in the
6440 current file. The corresponding variables are `org-todo-keywords'
6441 and `org-todo-interpretation'.
6444 File: org, Node: The very busy C-c C-c key, Next: Clean view, Prev: In-buffer settings, Up: Miscellaneous
6446 14.4 The very busy C-c C-c key
6447 ==============================
6449 The key `C-c C-c' has many purposes in org-mode, which are all
6450 mentioned scattered throughout this manual. One specific function of
6451 this key is to add _tags_ to a headline (*note Tags::). In many other
6452 circumstances it means something like _Hey Org-mode, look here and
6453 update according to what you see here_. Here is a summary of what this
6454 means in different contexts.
6456 - If there are highlights in the buffer from the creation of a sparse
6457 tree, or from clock display, remove these highlights.
6459 - If the cursor is in one of the special `#+KEYWORD' lines, this
6460 triggers scanning the buffer for these lines and updating the
6463 - If the cursor is inside a table, realign the table. This command
6464 works even if the automatic table editor has been turned off.
6466 - If the cursor is on a `#+TBLFM' line, re-apply the formulas to the
6469 - If the cursor is inside a table created by the `table.el' package,
6470 activate that table.
6472 - If the current buffer is a remember buffer, close the note and
6473 file it. With a prefix argument, file it, without further
6474 interaction, to the default location.
6476 - If the cursor is on a `<<<target>>>', update radio targets and
6477 corresponding links in this buffer.
6479 - If the cursor is in a property line or at the start or end of a
6480 property drawer, offer property commands.
6482 - If the cursor is in a plain list item with a checkbox, toggle the
6483 status of the checkbox.
6485 - If the cursor is on a numbered item in a plain list, renumber the
6488 - If the cursor is on the `#+BEGIN' line of a dynamical block, the
6492 File: org, Node: Clean view, Next: TTY keys, Prev: The very busy C-c C-c key, Up: Miscellaneous
6494 14.5 A cleaner outline view
6495 ===========================
6497 Some people find it noisy and distracting that the Org-mode headlines
6498 are starting with a potentially large number of stars. For example the
6499 tree from *Note Headlines:::
6501 * Top level headline
6507 * Another top level headline
6509 Unfortunately this is deeply ingrained into the code of Org-mode and
6510 cannot be easily changed. You can, however, modify the display in such
6511 a way that all leading stars become invisible and the outline more easy
6512 to read. To do this, customize the variable `org-hide-leading-stars'
6515 (setq org-hide-leading-stars t)
6517 or change this on a per-file basis with one of the lines (anywhere in
6520 #+STARTUP: showstars
6521 #+STARTUP: hidestars
6523 Press `C-c C-c' with the cursor in a `STARTUP' line to activate the
6526 With stars hidden, the tree becomes:
6528 * Top level headline
6534 * Another top level headline
6536 Note that the leading stars are not truly replaced by whitespace, they
6537 are only fontified with the face `org-hide' that uses the background
6538 color as font color. If you are not using either white or black
6539 background, you may have to customize this face to get the wanted
6540 effect. Another possibility is to set this font such that the extra
6541 stars are almost invisible, for example using the color `grey90' on a
6544 Things become cleaner still if you skip all the even levels and use
6545 only odd levels 1, 3, 5..., effectively adding two stars to go from one
6546 outline level to the next:
6548 * Top level headline
6554 * Another top level headline
6556 In order to make the structure editing and export commands handle this
6557 convention correctly, use
6559 (setq org-odd-levels-only t)
6561 or set this on a per-file basis with one of the following lines (don't
6562 forget to press `C-c C-c' with the cursor in the startup line to
6563 activate changes immediately).
6568 You can convert an Org-mode file from single-star-per-level to the
6569 double-star-per-level convention with `M-x org-convert-to-odd-levels
6570 RET' in that file. The reverse operation is `M-x
6571 org-convert-to-oddeven-levels'.
6574 File: org, Node: TTY keys, Next: Interaction, Prev: Clean view, Up: Miscellaneous
6576 14.6 Using org-mode on a tty
6577 ============================
6579 Org-mode uses a number of keys that are not accessible on a tty. This
6580 applies to most special keys like cursor keys, <TAB> and <RET>, when
6581 these are combined with modifier keys like <Meta> and/or <Shift>.
6582 Org-mode uses these bindings because it needs to provide keys for a
6583 large number of commands, and because these keys appeared particularly
6584 easy to remember. In order to still be able to access the core
6585 functionality of Org-mode on a tty, alternative bindings are provided.
6586 Here is a complete list of these bindings, which are obviously more
6587 cumbersome to use. Note that sometimes a work-around can be better.
6588 For example changing a time stamp is really only fun with `S-<cursor>'
6589 keys. On a tty you would rather use `C-c .' to re-insert the
6592 Default Alternative 1 Alternative 2
6593 `S-<TAB>' `C-u <TAB>'
6594 `M-<left>' `C-c C-x l' `<Esc> <left>'
6595 `M-S-<left>'`C-c C-x L'
6596 `M-<right>' `C-c C-x r' `<Esc>
6598 `M-S-<right>'`C-c C-x R'
6599 `M-<up>' `C-c C-x u' `<Esc> <up>'
6600 `M-S-<up>' `C-c C-x U'
6601 `M-<down>' `C-c C-x d' `<Esc> <down>'
6602 `M-S-<down>'`C-c C-x D'
6603 `S-<RET>' `C-c C-x c'
6604 `M-<RET>' `C-c C-x m' `<Esc> <RET>'
6605 `M-S-<RET>' `C-c C-x M'
6606 `S-<left>' `C-c <left>'
6607 `S-<right>' `C-c <right>'
6609 `S-<down>' `C-c <down>'
6610 `C-S-<left>'`C-c C-x
6612 `C-S-<right>'`C-c C-x
6616 File: org, Node: Interaction, Next: Bugs, Prev: TTY keys, Up: Miscellaneous
6618 14.7 Interaction with other packages
6619 ====================================
6621 Org-mode lives in the world of GNU Emacs and interacts in various ways
6622 with other code out there.
6626 * Cooperation:: Packages Org-mode cooperates with
6627 * Conflicts:: Packages that lead to conflicts
6630 File: org, Node: Cooperation, Next: Conflicts, Prev: Interaction, Up: Interaction
6632 14.7.1 Packages that Org-mode cooperates with
6633 ---------------------------------------------
6635 `calc.el' by Dave Gillespie
6636 Org-mode uses the calc package for implementing spreadsheet
6637 functionality in its tables (*note The spreadsheet::). Org-mode
6638 checks for the availability of calc by looking for the function
6639 `calc-eval' which should be autoloaded in your setup if calc has
6640 been installed properly. As of Emacs 22, calc is part of the Emacs
6641 distribution. Another possibility for interaction between the two
6642 packages is using calc for embedded calculations. *Note Embedded
6643 Mode: (calc)Embedded Mode.
6645 `constants.el' by Carsten Dominik
6646 In a table formula (*note The spreadsheet::), it is possible to use
6647 names for natural constants or units. Instead of defining your own
6648 constants in the variable `org-table-formula-constants', install
6649 the `constants' package which defines a large number of constants
6650 and units, and lets you use unit prefixes like `M' for `Mega' etc.
6651 You will need version 2.0 of this package, available at
6652 `http://www.astro.uva.nl/~dominik/Tools'. Org-mode checks for the
6653 function `constants-get', which has to be autoloaded in your
6654 setup. See the installation instructions in the file
6657 `cdlatex.el' by Carsten Dominik
6658 Org-mode can make use of the cdlatex package to efficiently enter
6659 LaTeX fragments into Org-mode files. See *Note CDLaTeX mode::.
6661 `remember.el' by John Wiegley
6662 Org mode cooperates with remember, see *Note Remember::.
6663 `Remember.el' is not part of Emacs, find it on the web.
6665 `table.el' by Takaaki Ota
6666 Complex ASCII tables with automatic line wrapping, column- and
6667 row-spanning, and alignment can be created using the Emacs table
6668 package by Takaaki Ota (`http://sourceforge.net/projects/table',
6669 and also part of Emacs 22). When <TAB> or `C-c C-c' is pressed in
6670 such a table, Org-mode will call `table-recognize-table' and move
6671 the cursor into the table. Inside a table, the keymap of Org-mode
6672 is inactive. In order to execute Org-mode-related commands, leave
6676 Recognize `table.el' table. Works when the cursor is in a
6680 Insert a table.el table. If there is already a table at
6681 point, this command converts it between the table.el format
6682 and the Org-mode format. See the documentation string of the
6683 command `org-convert-table' for the restrictions under which
6685 `table.el' is part of Emacs 22.
6687 `footnote.el' by Steven L. Baur
6688 Org-mode recognizes numerical footnotes as provided by this package
6689 (*note Footnotes::).
6692 File: org, Node: Conflicts, Prev: Cooperation, Up: Interaction
6694 14.7.2 Packages that lead to conflicts with Org-mode
6695 ----------------------------------------------------
6697 `allout.el' by Ken Manheimer
6698 Startup of Org-mode may fail with the error message
6699 `(wrong-type-argument keymapp nil)' when there is an outdated
6700 version `allout.el' on the load path, for example the version
6701 distributed with Emacs 21.x. Upgrade to Emacs 22 and this problem
6702 will disappear. If for some reason you cannot do this, make sure
6703 that org.el is loaded _before_ `allout.el', for example by putting
6704 `(require 'org)' early enough into your `.emacs' file.
6706 `CUA.el' by Kim. F. Storm
6707 Keybindings in Org-mode conflict with the `S-<cursor>' keys used
6708 by CUA-mode (as well as pc-select-mode and s-region-mode) to
6709 select and extend the region. If you want to use one of these
6710 packages along with Org-mode, configure the variable
6711 `org-CUA-compatible'. When set, Org-mode will move the following
6712 keybindings in Org-mode files, and in the agenda buffer (but not
6713 during date selection).
6715 S-UP -> M-p S-DOWN -> M-n
6716 S-LEFT -> M-- S-RIGHT -> M-+
6718 Yes, these are unfortunately more difficult to remember. If you
6719 want to have other replacement keys, look at the variable
6720 `org-disputed-keys'.
6722 `windmove.el' by Hovav Shacham
6723 Also this package uses the `S-<cursor>' keys, so everything written
6724 in the paragraph above about CUA mode also applies here.
6726 `footnote.el' by Steven L. Baur
6727 Org-mode supports the syntax of the footnote package, but only the
6728 numerical footnote markers. Also, the default key for footnote
6729 commands, `C-c !' is already used by Org-mode. You could use the
6730 variable `footnote-prefix' to switch footnotes commands to another
6731 key. Or, you could use `org-replace-disputed-keys' and
6732 `org-disputed-keys' to change the settings in Org-mode.
6736 File: org, Node: Bugs, Prev: Interaction, Up: Miscellaneous
6741 Here is a list of things that should work differently, but which I have
6742 found too hard to fix.
6744 * If a table field starts with a link, and if the corresponding table
6745 column is narrowed (*note Narrow columns::) to a width too small to
6746 display the link, the field would look entirely empty even though
6747 it is not. To prevent this, Org-mode throws an error. The
6748 work-around is to make the column wide enough to fit the link, or
6749 to add some text (at least 2 characters) before the link in the
6752 * Narrowing table columns does not work on XEmacs, because the
6753 `format' function does not transport text properties.
6755 * Text in an entry protected with the `QUOTE' keyword should not
6758 * When the application called by `C-c C-o' to open a file link fails
6759 (for example because the application does not exist or refuses to
6760 open the file), it does so silently. No error message is
6763 * Recalculating a table line applies the formulas from left to right.
6764 If a formula uses _calculated_ fields further down the row,
6765 multiple recalculation may be needed to get all fields consistent.
6766 You may use the command `org-table-iterate' (`C-u C-c *') to
6767 recalculate until convergence.
6769 * A single letter cannot be made bold, for example `*a*'.
6771 * The exporters work well, but could be made more efficient.
6774 File: org, Node: Extensions and Hacking, Next: History and Acknowledgments, Prev: Miscellaneous, Up: Top
6776 Appendix A Extensions, Hooks and Hacking
6777 ****************************************
6779 This appendix lists extensions for Org-mode written by other authors.
6780 It also covers some aspects where users can extend the functionality of
6785 * Extensions:: Existing 3rd-part extensions
6786 * Adding hyperlink types:: New custom link types
6787 * Tables in arbitrary syntax:: Orgtbl for LaTeX and other programs
6788 * Dynamic blocks:: Automatically filled blocks
6789 * Special agenda views:: Customized views
6790 * Using the property API:: Writing programs that use entry properties
6793 File: org, Node: Extensions, Next: Adding hyperlink types, Prev: Extensions and Hacking, Up: Extensions and Hacking
6795 A.1 Third-party extensions for Org-mode
6796 =======================================
6798 The following extensions for Org-mode have been written by other people:
6800 `org-publish.el' by David O'Toole
6801 This package provides facilities for publishing related sets of
6802 Org-mode files together with linked files like images as webpages.
6803 It is highly configurable and can be used for other publishing
6804 purposes as well. As of Org-mode version 4.30, `org-publish.el'
6805 is part of the Org-mode distribution. It is not yet part of
6806 Emacs, however, a delay caused by the preparations for the 22.1
6807 release. In the mean time, `org-publish.el' can be downloaded
6808 from David's site: `http://dto.freeshell.org/e/org-publish.el'.
6810 `org-mouse.el' by Piotr Zielinski
6811 This package implements extended mouse functionality for Org-mode.
6812 It allows you to cycle visibility and to edit the document
6813 structure with the mouse. Best of all, it provides a
6814 context-sensitive menu on <mouse-3> that changes depending on the
6815 context of a mouse-click. As of Org-mode version 4.53,
6816 `org-mouse.el' is part of the Org-mode distribution. It is not
6817 yet part of Emacs, however, a delay caused by the preparations for
6818 the 22.1 release. In the mean time, `org-mouse.el' can be
6819 downloaded from Piotr's site:
6820 `http://www.cl.cam.ac.uk/~pz215/files/org-mouse.el'.
6822 `org-blog.el' by David O'Toole
6823 A blogging plug-in for `org-publish.el'.
6824 `http://dto.freeshell.org/notebook/OrgMode.html'.
6826 `blorg.el' by Bastien Guerry
6827 Publish Org-mode files as blogs.
6828 `http://www.cognition.ens.fr/~guerry/blorg.html'.
6830 `org2rem.el' by Bastien Guerry
6831 Translates Org-mode files into something readable by Remind.
6832 `http://www.cognition.ens.fr/~guerry/u/org2rem.el'.
6834 `org-toc.el' by Bastien Guerry
6835 Produces a simple table of contents of an Org-mode file, for easy
6836 navigation. `http://www.cognition.ens.fr/~guerry/u/org2rem.el'.
6838 `org-registry.el' by Bastien Guerry
6839 Find which Org-file link to a certain document.
6840 `http://www.cognition.ens.fr/~guerry/u/org2rem.el'.
6843 File: org, Node: Adding hyperlink types, Next: Tables in arbitrary syntax, Prev: Extensions, Up: Extensions and Hacking
6845 A.2 Adding hyperlink types
6846 ==========================
6848 Org-mode has a large number of hyperlink types built-in (*note
6849 Hyperlinks::). If you would like to add new link types, it provides an
6850 interface for doing so. Lets look at an example file `org-man.el' that
6851 will add support for creating links like `[[man:printf][The printf
6852 manpage]]' to show unix manual pages inside emacs:
6854 ;;; org-man.el - Support for links to manpages in Org-mode
6858 (org-add-link-type "man" 'org-man-open)
6859 (add-hook 'org-store-link-functions 'org-man-store-link)
6861 (defcustom org-man-command 'man
6862 "The Emacs command to be used to display a man page."
6864 :type '(choice (const man) (const woman)))
6866 (defun org-man-open (path)
6867 "Visit the manpage on PATH.
6868 PATH should be a topic that can be thrown at the man command."
6869 (funcall org-man-command path))
6871 (defun org-man-store-link ()
6872 "Store a link to a manpage."
6873 (when (memq major-mode '(Man-mode woman-mode))
6874 ;; This is a man page, we do make this link
6875 (let* ((page (org-man-get-page-name))
6876 (link (concat "man:" page))
6877 (description (format "Manpage for %s" page)))
6878 (org-store-link-props
6881 :description description))))
6883 (defun org-man-get-page-name ()
6884 "Extract the page name from the buffer name."
6885 ;; This works for both `Man-mode' and `woman-mode'.
6886 (if (string-match " \\(\\S-+\\)\\*" (buffer-name))
6887 (match-string 1 (buffer-name))
6888 (error "Cannot create link to this man page")))
6892 ;;; org-man.el ends here
6894 You would activate this new link type in `.emacs' with
6898 Lets go through the file and see what it does.
6899 1. It does `(require 'org)' to make sure that `org.el' has been
6902 2. The next line calls `org-add-link-type' to define a new link type
6903 with prefix `man'. The call also contains the name of a function
6904 that will be called to follow such a link.
6906 3. The next line adds a function to `org-store-link-functions', in
6907 order to allow the command `C-c l' to record a useful link in a
6908 buffer displaying a man page.
6910 The rest of the file defines the necessary variables and functions.
6911 First there is a customization variable that determines which emacs
6912 command should be used to display manpages. There are two options,
6913 `man' and `woman'. Then the function to follow a link is defined. It
6914 gets the link path as an argument - in this case the link path is just
6915 a topic for the manual command. The function calls the value of
6916 `org-man-command' to display the man page.
6918 Finally the function `org-man-store-link' is defined. When you try
6919 to store a link with `C-c l', also this function will be called to try
6920 to make a link. The function must first decide if it is supposed to
6921 create the link for this buffer type, we do this by checking the value
6922 of the variable `major-mode'. If not, the function must exit and
6923 retunr the value `nil'. If yes, the link is created by getting the
6924 manual tpoic from the buffer name and prefixing it with the string
6925 `man:'. Then it must call the command `org-store-link-props' and set
6926 the `:type' and `:link' properties. Optionally you can also set the
6927 `:description' property to provide a default for the link description
6928 when the link is later inserted into tan Org-mode buffer with `C-c C-l'.
6931 File: org, Node: Tables in arbitrary syntax, Next: Dynamic blocks, Prev: Adding hyperlink types, Up: Extensions and Hacking
6933 A.3 Tables in arbitrary syntax
6934 ==============================
6936 Since Orgtbl-mode can be used as a minor mode in arbitrary buffers, a
6937 frequent feature request has been to make it work with native tables in
6938 specific languages, for example LaTeX. However, this is extremely hard
6939 to do in a general way, would lead to a customization nightmare, and
6940 would take away much of the simplicity of the Orgtbl-mode table editor.
6942 This appendix describes a different approach. We keep the
6943 Orgtbl-mode table in its native format (the source table), and use a
6944 custom function to translate the table to the correct syntax, and to
6945 install it in the right location (the target table). This puts the
6946 burden of writing conversion functions on the user, but it allows for a
6947 very flexible system.
6951 * Radio tables:: Sending and receiving
6952 * A LaTeX example:: Step by step, almost a tutorial
6953 * Translator functions:: Copy and modify
6956 File: org, Node: Radio tables, Next: A LaTeX example, Prev: Tables in arbitrary syntax, Up: Tables in arbitrary syntax
6961 To define the location of the target table, you first need to create two
6962 lines that are comments in the current mode, but contain magic words for
6963 Orgtbl-mode to find. Orgtbl-mode will insert the translated table
6964 between these lines, replacing whatever was there before. For example:
6966 /* BEGIN RECEIVE ORGTBL table_name */
6967 /* END RECEIVE ORGTBL table_name */
6969 Just above the source table, we put a special line that tells
6970 Orgtbl-mode how to translate this table and where to install it. For
6972 #+ORGTBL: SEND table_name translation_function arguments....
6974 `table_name' is the reference name for the table that is also used in
6975 the receiver lines. `translation_function' is the Lisp function that
6976 does the translation. Furthermore, the line can contain a list of
6977 arguments (alternating key and value) at the end. The arguments will be
6978 passed as a property list to the translation function for
6979 interpretation. A few standard parameters are already recognized and
6980 acted upon before the translation function is called:
6983 Skip the first N lines of the table. Hlines do count!
6985 `:skipcols (n1 n2 ...)'
6986 List of columns that should be skipped. If the table has a column
6987 with calculation marks, that column is automatically discarded as
6988 well. Please note that the translator function sees the table
6989 _after_ the removal of these columns, the function never knows
6990 that there have been additional columns.
6992 The one problem remaining is how to keep the source table in the buffer
6993 without disturbing the normal workings of the file, for example during
6994 compilation of a C file or processing of a LaTeX file. There are a
6995 number of different solutions:
6997 * The table could be placed in a block comment if that is supported
6998 by the language. For example, in C-mode you could wrap the table
6999 between `/*' and `*/' lines.
7001 * Sometimes it is possible to put the table after some kind of END
7002 statement, for example `\bye' in TeX and `\end{document}' in LaTeX.
7004 * You can just comment the table line by line whenever you want to
7005 process the file, and uncomment it whenever you need to edit the
7006 table. This only sounds tedious - the command `M-x
7007 orgtbl-toggle-comment' does make this comment-toggling very easy,
7008 in particular if you bind it to a key.
7011 File: org, Node: A LaTeX example, Next: Translator functions, Prev: Radio tables, Up: Tables in arbitrary syntax
7013 A.3.2 A LaTeX example
7014 ---------------------
7016 The best way to wrap the source table in LaTeX is to use the `comment'
7017 environment provided by `comment.sty'. It has to be activated by
7018 placing `\usepackage{comment}' into the document header. Orgtbl-mode
7019 can insert a radio table skeleton(1) with the command `M-x
7020 orgtbl-insert-radio-table'. You will be prompted for a table name,
7021 lets say we use `salesfigures'. You will then get the following
7024 % BEGIN RECEIVE ORGTBL salesfigures
7025 % END RECEIVE ORGTBL salesfigures
7027 #+ORGTBL: SEND salesfigures orgtbl-to-latex
7031 The `#+ORGTBL: SEND' line tells orgtbl-mode to use the function
7032 `orgtbl-to-latex' to convert the table into LaTeX and to put it into
7033 the receiver location with name `salesfigures'. You may now fill in
7034 the table, feel free to use the spreadsheet features(2):
7036 % BEGIN RECEIVE ORGTBL salesfigures
7037 % END RECEIVE ORGTBL salesfigures
7039 #+ORGTBL: SEND salesfigures orgtbl-to-latex
7040 | Month | Days | Nr sold | per day |
7041 |-------+------+---------+---------|
7042 | Jan | 23 | 55 | 2.4 |
7043 | Feb | 21 | 16 | 0.8 |
7044 | March | 22 | 278 | 12.6 |
7045 #+TBLFM: $4=$3/$2;%.1f
7046 % $ (optional extra dollar to keep font-lock happy, see footnote)
7049 When you are done, press `C-c C-c' in the table to get the converted
7050 table inserted between the two marker lines.
7052 Now lets assume you want to make the table header by hand, because
7053 you want to control how columns are aligned etc. In this case we make
7054 sure that the table translator does skip the first 2 lines of the source
7055 table, and tell the command to work as a splice, i.e. to not produce
7056 header and footer commands of the target table:
7058 \begin{tabular}{lrrr}
7059 Month & \multicolumn{1}{c}{Days} & Nr.\ sold & per day\\
7060 % BEGIN RECEIVE ORGTBL salesfigures
7061 % END RECEIVE ORGTBL salesfigures
7065 #+ORGTBL: SEND salesfigures orgtbl-to-latex :splice t :skip 2
7066 | Month | Days | Nr sold | per day |
7067 |-------+------+---------+---------|
7068 | Jan | 23 | 55 | 2.4 |
7069 | Feb | 21 | 16 | 0.8 |
7070 | March | 22 | 278 | 12.6 |
7071 #+TBLFM: $4=$3/$2;%.1f
7074 The LaTeX translator function `orgtbl-to-latex' is already part of
7075 Orgtbl-mode. It uses a `tabular' environment to typeset the table and
7076 marks horizontal lines with `\hline'. Furthermore, it interprets the
7077 following parameters:
7080 When set to t, return only table body lines, don't wrap them into a
7081 tabular environment. Default is nil.
7084 A format to be used to wrap each field, should contain `%s' for the
7085 original field value. For example, to wrap each field value in
7086 dollars, you could use `:fmt "$%s$"'. This may also be a property
7087 list with column numbers and formats. for example `:fmt (2 "$%s$"
7091 Use this format to print numbers with exponentials. The format
7092 should have `%s' twice for inserting mantissa and exponent, for
7093 example `"%s\\times10^{%s}"'. The default is `"%s\\,(%s)"'. This
7094 may also be a property list with column numbers and formats, for
7095 example `:efmt (2 "$%s\\times10^{%s}$" 4 "$%s\\cdot10^{%s}$")'.
7096 After `efmt' has been applied to a value, `fmt' will also be
7099 ---------- Footnotes ----------
7101 (1) By default this works only for LaTeX, HTML, and TeXInfo.
7102 Configure the variable `orgtbl-radio-tables' to install templates for
7105 (2) If the `#+TBLFM' line contains an odd number of dollar
7106 characters, this may cause problems with font-lock in latex-mode. As
7107 shown in the example you can fix this by adding an extra line inside the
7108 `comment' environment that is used to balance the dollar expressions.
7109 If you are using AUCTeX with the font-latex library, a much better
7110 solution is to add the `comment' environment to the variable
7111 `LaTeX-verbatim-environments'.
7114 File: org, Node: Translator functions, Prev: A LaTeX example, Up: Tables in arbitrary syntax
7116 A.3.3 Translator functions
7117 --------------------------
7119 Orgtbl-mode has several translator functions built-in:
7120 `orgtbl-to-latex', `orgtbl-to-html', and `orgtbl-to-texinfo'. Except
7121 for `orgtbl-to-html'(1), these all use a generic translator,
7122 `orgtbl-to-generic'. For example, `orgtbl-to-latex' itself is a very
7123 short function that computes the column definitions for the `tabular'
7124 environment, defines a few field and line separators and then hands
7125 over to the generic translator. Here is the entire code:
7127 (defun orgtbl-to-latex (table params)
7128 "Convert the orgtbl-mode TABLE to LaTeX."
7129 (let* ((alignment (mapconcat (lambda (x) (if x "r" "l"))
7130 org-table-last-alignment ""))
7133 :tstart (concat "\\begin{tabular}{" alignment "}")
7134 :tend "\\end{tabular}"
7135 :lstart "" :lend " \\\\" :sep " & "
7136 :efmt "%s\\,(%s)" :hline "\\hline")))
7137 (orgtbl-to-generic table (org-combine-plists params2 params))))
7139 As you can see, the properties passed into the function (variable
7140 PARAMS) are combined with the ones newly defined in the function
7141 (variable PARAMS2). The ones passed into the function (i.e. the ones
7142 set by the `ORGTBL SEND' line) take precedence. So if you would like
7143 to use the LaTeX translator, but wanted the line endings to be
7144 `\\[2mm]' instead of the default `\\', you could just overrule the
7147 #+ORGTBL: SEND test orgtbl-to-latex :lend " \\\\[2mm]"
7149 For a new language, you can either write your own converter function
7150 in analogy with the LaTeX translator, or you can use the generic
7151 function directly. For example, if you have a language where a table
7152 is started with `!BTBL!', ended with `!ETBL!', and where table lines are
7153 started with `!BL!', ended with `!EL!' and where the field separator is
7154 a TAB, you could call the generic translator like this (on a single
7157 #+ORGTBL: SEND test orgtbl-to-generic :tstart "!BTBL!" :tend "!ETBL!"
7158 :lstart "!BL! " :lend " !EL!" :sep "\t"
7160 Please check the documentation string of the function
7161 `orgtbl-to-generic' for a full list of parameters understood by that
7162 function and remember that you can pass each of them into
7163 `orgtbl-to-latex', `orgtbl-to-texinfo', and any other function using
7164 the generic function.
7166 Of course you can also write a completely new function doing
7167 complicated things the generic translator cannot do. A translator
7168 function takes two arguments. The first argument is the table, a list
7169 of lines, each line either the symbol `hline' or a list of fields. The
7170 second argument is the property list containing all parameters
7171 specified in the `#+ORGTBL: SEND' line. The function must return a
7172 single string containing the formatted table. If you write a generally
7173 useful translator, please post it on `emacs-orgmode@gnu.org' so that
7174 others can benefit from your work.
7176 ---------- Footnotes ----------
7178 (1) The HTML translator uses the same code that produces tables
7182 File: org, Node: Dynamic blocks, Next: Special agenda views, Prev: Tables in arbitrary syntax, Up: Extensions and Hacking
7187 Org-mode documents can contain _dynamic blocks_. These are specially
7188 marked regions that are updated by some user-written function. A good
7189 example for such a block is the clock table inserted by the command
7190 `C-c C-x C-r' (*note Clocking work time::).
7192 Dynamic block are enclosed by a BEGIN-END structure that assigns a
7193 name to the block and can also specify parameters for the function
7194 producing the content of the block.
7196 #+BEGIN: myblock :parameter1 value1 :parameter2 value2 ...
7200 Dynamic blocks are updated with the following commands
7203 Update dynamic block at point.
7206 Update all dynamic blocks in the current file.
7208 Updating a dynamic block means to remove all the text between BEGIN
7209 and END, parse the BEGIN line for parameters and then call the specific
7210 writer function for this block to insert the new content. For a block
7211 with name `myblock', the writer function is `org-dblock-write:myblock'
7212 with as only parameter a property list with the parameters given in the
7213 begin line. Here is a trivial example of a block that keeps track of
7214 when the block update function was last run:
7216 #+BEGIN: block-update-time :format "on %m/%d/%Y at %H:%M"
7220 The corresponding block writer function could look like this:
7222 (defun org-dblock-write:block-update-time (params)
7223 (let ((fmt (or (plist-get params :format) "%d. %m. %Y")))
7224 (insert "Last block update at: "
7225 (format-time-string fmt (current-time)))))
7227 If you want to make sure that all dynamic blocks are always
7228 up-to-date, you could add the function `org-update-all-dblocks' to a
7229 hook, for example `before-save-hook'. `org-update-all-dblocks' is
7230 written in a way that is does nothing in buffers that are not in
7234 File: org, Node: Special agenda views, Next: Using the property API, Prev: Dynamic blocks, Up: Extensions and Hacking
7236 A.5 Special Agenda Views
7237 ========================
7239 Org-mode provides a special hook that can be used to narrow down the
7240 selection made by any of the agenda views. You may specify a function
7241 that is used at each match to verify if the match should indeed be part
7242 of the agenda view, and if not, how much should be skipped.
7244 Let's say you want to produce a list of projects that contain a
7245 WAITING tag anywhere in the project tree. Let's further assume that
7246 you have marked all tree headings that define a project with the todo
7247 keyword PROJECT. In this case you would run a todo search for the
7248 keyword PROJECT, but skip the match unless there is a WAITING tag
7249 anywhere in the subtree belonging to the project line.
7251 To achieve this, you must write a function that searches the subtree
7252 for the tag. If the tag is found, the function must return `nil' to
7253 indicate that this match should not be skipped. If there is no such
7254 tag, return the location of the end of the subtree, to indicate that
7255 search should continue from there.
7257 (defun my-skip-unless-waiting ()
7258 "Skip trees that are not waiting"
7259 (let ((subtree-end (save-excursion (org-end-of-subtree t))))
7260 (if (re-search-forward ":WAITING:" subtree-end t)
7261 nil ; tag found, do not skip
7262 subtree-end))) ; tag not found, continue after end of subtree
7264 Now you may use this function in an agenda custom command, for
7267 (org-add-agenda-custom-command
7268 '("b" todo "PROJECT"
7269 ((org-agenda-skip-function 'my-org-waiting-projects)
7270 (org-agenda-overriding-header "Projects waiting for something: "))))
7272 Note that this also binds `org-agenda-overriding-header' to get a
7273 meaningful header in the agenda view.
7275 You may also put a Lisp form into `org-agenda-skip-function'. In
7276 particular, you may use the functions `org-agenda-skip-entry-if' and
7277 `org-agenda-skip-subtree-if' in this form, for example:
7279 `'(org-agenda-skip-entry-if 'scheduled)'
7280 Skip current entry if it has been scheduled.
7282 `'(org-agenda-skip-entry-if 'notscheduled)'
7283 Skip current entry if it has not been scheduled.
7285 `'(org-agenda-skip-entry-if 'deadline)'
7286 Skip current entry if it has a deadline.
7288 `'(org-agenda-skip-entry-if 'scheduled 'deadline)'
7289 Skip current entry if it has a deadline, or if it is scheduled.
7291 `'(org-agenda-skip-entry 'regexp "regular expression")'
7292 Skip current entry if the regular expression matches in the entry.
7294 `'(org-agenda-skip-entry 'notregexp "regular expression")'
7295 Skip current entry unless the regular expression matches.
7297 `'(org-agenda-skip-subtree-if 'regexp "regular expression")'
7298 Same as above, but check and skip the entire subtree.
7300 Therefore we could also have written the search for WAITING projects
7301 like this, even without defining a special function:
7303 (org-add-agenda-custom-command
7304 '("b" todo "PROJECT"
7305 ((org-agenda-skip-function '(org-agenda-skip-subtree-if
7306 'regexp ":WAITING:"))
7307 (org-agenda-overriding-header "Projects waiting for something: "))))
7310 File: org, Node: Using the property API, Prev: Special agenda views, Up: Extensions and Hacking
7312 A.6 Using the property API
7313 ==========================
7315 Here is a description of the functions that can be used to work with
7318 -- Function: org-entry-properties &optional pom which
7319 Get all properties of the entry at point-or-marker POM. This
7320 includes the TODO keyword, the tags, time strings for deadline,
7321 scheduled, and clocking, and any additional properties defined in
7322 the entry. The return value is an alist, keys may occur multiple
7323 times if the property key was used several times. POM may also be
7324 nil, in which case the current entry is used. If WHICH is nil or
7325 `all', get all properties. If WHICH is `special' or `standard',
7326 only get that subclass.
7328 -- Function: org-entry-get pom property &optional inherit
7329 Get value of PROPERTY for entry at point-or-marker POM. If
7330 INHERIT is non-nil and the entry does not have the property, then
7331 also check higher levels of the hierarchy.
7333 -- Function: org-entry-delete pom property
7334 Delete the property PROPERTY from entry at point-or-marker POM.
7336 -- Function: org-entry-put pom property value
7337 Set PROPERTY to VALUE for entry at point-or-marker POM.
7339 -- Function: org-buffer-property-keys &optional include-specials
7340 Get all property keys in the current buffer.
7342 -- Function: org-insert-property-drawer
7343 Insert a property drawer at point.
7346 File: org, Node: History and Acknowledgments, Next: Index, Prev: Extensions and Hacking, Up: Top
7348 Appendix B History and Acknowledgments
7349 **************************************
7351 Org-mode was borne in 2003, out of frustration over the user interface
7352 of the Emacs outline-mode. I was trying to organize my notes and
7353 projects, and using Emacs seemed to be the natural way to go. However,
7354 having to remember eleven different commands with two or three keys per
7355 command, only to hide and unhide parts of the outline tree, that seemed
7356 entirely unacceptable to me. Also, when using outlines to take notes, I
7357 constantly want to restructure the tree, organizing it parallel to my
7358 thoughts and plans. _Visibility cycling_ and _structure editing_ were
7359 originally implemented in the package `outline-magic.el', but quickly
7360 moved to the more general `org.el'. As this environment became
7361 comfortable for project planning, the next step was adding _TODO
7362 entries_, basic _time stamps_, and _table support_. These areas
7363 highlight the two main goals that Org-mode still has today: To create a
7364 new, outline-based, plain text mode with innovative and intuitive
7365 editing features, and to incorporate project planning functionality
7366 directly into a notes file.
7368 Since the first release, literally thousands of emails to me or on
7369 `emacs-orgmode@gnu.org' have provided a constant stream of bug reports,
7370 feedback, new ideas, and sometimes patches and add-on code. Many
7371 thanks to everyone who has helped to improve this package. I am trying
7372 to keep here a list of the people who had significant influence in
7373 shaping one or more aspects of Org-mode. The list may not be complete,
7374 if I have forgotten someone, please accept my apologies and let me know.
7376 * Russel Adams came up with the idea for drawers.
7378 * Thomas Baumann contributed the code for links to the MH-E email
7381 * Alex Bochannek provided a patch for rounding time stamps.
7383 * Charles Cave's suggestion sparked the implementation of templates
7386 * Pavel Chalmoviansky influenced the agenda treatment of items with
7389 * Gregory Chernov patched support for lisp forms into table
7390 calculations and improved XEmacs compatibility, in particular by
7391 porting `nouline.el' to XEmacs.
7393 * Sacha Chua suggested to copy some linking code from Planner.
7395 * Eddward DeVilla proposed and tested checkbox statistics. He also
7396 came up with the idea of properties, and that there should be an
7399 * Kees Dullemond used to edit projects lists directly in HTML and so
7400 inspired some of the early development, including HTML export. He
7401 also asked for a way to narrow wide table columns.
7403 * Christian Egli converted the documentation into TeXInfo format,
7404 patched CSS formatting into the HTML exporter, and inspired the
7407 * David Emery provided a patch for custom CSS support in exported
7410 * Nic Ferrier contributed mailcap and XOXO support.
7412 * John Foerch figured out how to make incremental search show context
7413 around a match in a hidden outline tree.
7415 * Niels Giessen had the idea to automatically archive DONE trees.
7417 * Bastien Guerry wrote the LaTeX exporter and has been prolific with
7418 patches, ideas, and bug reports.
7420 * Kai Grossjohann pointed out key-binding conflicts with other
7423 * Scott Jaderholm proposed footnotes, control over whitespace between
7424 folded entries, and column view for properties.
7426 * Shidai Liu ("Leo") asked for embedded LaTeX and tested it. He also
7427 provided frequent feedback and some patches.
7429 * Jason F. McBrayer suggested agenda export to CSV format.
7431 * Dmitri Minaev sent a patch to set priority limits on a per-file
7434 * Stefan Monnier provided a patch to keep the Emacs-Lisp compiler
7437 * Rick Moynihan proposed to allow multiple TODO sequences in a file.
7439 * Todd Neal provided patches for links to Info files and elisp forms.
7441 * Tim O'Callaghan suggested in-file links, search options for general
7442 file links, and TAGS.
7444 * Takeshi Okano translated the manual and David O'Toole's tutorial
7447 * Oliver Oppitz suggested multi-state TODO items.
7449 * Scott Otterson sparked the introduction of descriptive text for
7450 links, among other things.
7452 * Pete Phillips helped during the development of the TAGS feature,
7453 and provided frequent feedback.
7455 * T.V. Raman reported bugs and suggested improvements.
7457 * Matthias Rempe (Oelde) provided ideas, Windows support, and quality
7460 * Kevin Rogers contributed code to access VM files on remote hosts.
7462 * Frank Ruell solved the mystery of the `keymapp nil' bug, a
7463 conflict with `allout.el'.
7465 * Jason Riedy sent a patch to fix a bug with export of TODO keywords.
7467 * Philip Rooke created the Org-mode reference card and provided lots
7470 * Christian Schlauer proposed angular brackets around links, among
7473 * Linking to VM/BBDB/GNUS was inspired by Tom Shannon's
7474 `organizer-mode.el'.
7476 * Daniel Sinder came up with the idea of internal archiving by
7479 * Dale Smith proposed link abbreviations.
7481 * Adam Spiers asked for global linking commands and inspired the link
7482 extension system. support mairix.
7484 * David O'Toole wrote `org-publish.el' and drafted the manual
7485 chapter about publishing.
7487 * Ju"rgen Vollmer contributed code generating the table of contents
7490 * Chris Wallace provided a patch implementing the `QUOTE' keyword.
7492 * David Wainberg suggested archiving, and improvements to the linking
7495 * John Wiegley wrote `emacs-wiki.el' and `planner.el'. The
7496 development of Org-mode was fully independent, and both systems are
7497 really different beasts in their basic ideas and implementation
7498 details. I later looked at John's code, however, and learned from
7499 his implementation of (i) links where the link itself is hidden
7500 and only a description is shown, and (ii) popping up a calendar to
7501 select a date. John has also contributed a number of great ideas
7502 directly to Org-mode.
7504 * Carsten Wimmer suggested some changes and helped fix a bug in
7507 * Roland Winkler requested additional keybindings to make Org-mode
7510 * Piotr Zielinski wrote `org-mouse.el', proposed agenda blocks and
7511 contributed various ideas and code snippets.
7514 File: org, Node: Index, Next: Key Index, Prev: History and Acknowledgments, Up: Top
7522 * abbreviation, links: Link abbreviations. (line 6)
7523 * acknowledgments: History and Acknowledgments.
7525 * action, for publishing: Publishing action. (line 6)
7526 * activation: Activation. (line 6)
7527 * active region <1>: ASCII export. (line 9)
7528 * active region <2>: Structure editing. (line 70)
7529 * active region <3>: Built-in table editor.
7531 * active region: HTML Export commands.
7533 * agenda: Weekly/Daily agenda. (line 6)
7534 * agenda dispatcher: Agenda dispatcher. (line 6)
7535 * agenda files: Agenda files. (line 6)
7536 * agenda files, removing buffers: Agenda commands. (line 244)
7537 * agenda views: Agenda views. (line 6)
7538 * agenda views, custom: Custom agenda views. (line 6)
7539 * agenda views, exporting <1>: Agenda commands. (line 233)
7540 * agenda views, exporting: Exporting Agenda Views.
7542 * agenda views, user-defined: Special agenda views.
7544 * agenda, pipe: Extracting Agenda Information for other programs.
7546 * agenda, with block views: Block agenda. (line 6)
7547 * align, STARTUP keyword: In-buffer settings. (line 68)
7548 * allout.el: Conflicts. (line 6)
7549 * angular brackets, around links: External links. (line 43)
7550 * API, for properties <1>: Property API. (line 6)
7551 * API, for properties: Using the property API.
7553 * appointment reminders: Weekly/Daily agenda. (line 66)
7554 * appt.el: Weekly/Daily agenda. (line 66)
7555 * archive locations: Moving subtrees. (line 23)
7556 * archiving: Archiving. (line 6)
7557 * ASCII export: ASCII export. (line 6)
7558 * author: Feedback. (line 6)
7559 * author info, in export: Export options. (line 26)
7560 * autoload: Activation. (line 6)
7561 * backtrace of an error: Feedback. (line 27)
7562 * BBDB links: External links. (line 6)
7563 * block agenda: Block agenda. (line 6)
7564 * blorg.el: Extensions. (line 32)
7565 * bold text: Enhancing text. (line 15)
7566 * Boolean logic, for tag searches: Tag searches. (line 24)
7567 * bug reports: Feedback. (line 6)
7568 * bugs: Bugs. (line 6)
7569 * C-c C-c, overview: The very busy C-c C-c key.
7571 * calc package: The spreadsheet. (line 6)
7572 * calc.el: Cooperation. (line 6)
7573 * calculations, in tables <1>: The spreadsheet. (line 6)
7574 * calculations, in tables: Built-in table editor.
7576 * calendar commands, from agenda: Agenda commands. (line 196)
7577 * calendar integration: Weekly/Daily agenda. (line 24)
7578 * calendar, for selecting date: The date/time prompt.
7580 * category: Categories. (line 6)
7581 * CDLaTeX: CDLaTeX mode. (line 6)
7582 * cdlatex.el: Cooperation. (line 29)
7583 * checkbox statistics: Checkboxes. (line 23)
7584 * checkboxes: Checkboxes. (line 6)
7585 * children, subtree visibility state: Visibility cycling. (line 10)
7586 * clean outline view: Clean view. (line 6)
7587 * column formula: Column formulas. (line 6)
7588 * column view, for properties: Defining columns. (line 6)
7589 * commands, in agenda buffer: Agenda commands. (line 6)
7590 * comment lines: Comment lines. (line 6)
7591 * completion, of dictionary words: Completion. (line 6)
7592 * completion, of file names: Handling links. (line 44)
7593 * completion, of link abbreviations: Completion. (line 6)
7594 * completion, of links: Handling links. (line 25)
7595 * completion, of option keywords <1>: Per file keywords. (line 23)
7596 * completion, of option keywords <2>: Completion. (line 6)
7597 * completion, of option keywords: Export options. (line 6)
7598 * completion, of property keys: Completion. (line 6)
7599 * completion, of tags <1>: Completion. (line 6)
7600 * completion, of tags: Setting tags. (line 11)
7601 * completion, of TeX symbols: Completion. (line 6)
7602 * completion, of TODO keywords <1>: Completion. (line 6)
7603 * completion, of TODO keywords: Workflow states. (line 15)
7604 * constants, in calculations: References. (line 82)
7605 * constants.el: Cooperation. (line 14)
7606 * constcgs, STARTUP keyword: In-buffer settings. (line 94)
7607 * constSI, STARTUP keyword: In-buffer settings. (line 94)
7608 * content, STARTUP keyword: In-buffer settings. (line 61)
7609 * contents, global visibility state: Visibility cycling. (line 22)
7610 * copying, of subtrees: Structure editing. (line 6)
7611 * creating timestamps: Creating timestamps. (line 6)
7612 * CUA.el: Conflicts. (line 15)
7613 * custom agenda views: Custom agenda views. (line 6)
7614 * custom date/time format: Custom time format. (line 6)
7615 * custom search strings: Custom searches. (line 6)
7616 * customization: Customization. (line 6)
7617 * customtime, STARTUP keyword: In-buffer settings. (line 91)
7618 * cutting, of subtrees: Structure editing. (line 6)
7619 * cycling, of TODO states: TODO basics. (line 13)
7620 * cycling, visibility: Visibility cycling. (line 6)
7621 * daily agenda: Weekly/Daily agenda. (line 6)
7622 * date format, custom: Custom time format. (line 6)
7623 * date range: Time stamps. (line 40)
7624 * date stamps <1>: Timestamps. (line 6)
7625 * date stamps: Time stamps. (line 6)
7626 * date, reading in minibuffer: The date/time prompt.
7628 * DEADLINE keyword: Deadlines and scheduling.
7630 * deadlines: Time stamps. (line 6)
7631 * debugging, of table formulas: Editing and debugging formulas.
7633 * demotion, of subtrees: Structure editing. (line 6)
7634 * diary entries, creating from agenda: Agenda commands. (line 201)
7635 * diary integration: Weekly/Daily agenda. (line 24)
7636 * dictionary word completion: Completion. (line 6)
7637 * directories, for publishing: Sources and destinations.
7639 * dispatching agenda commands: Agenda dispatcher. (line 6)
7640 * display changing, in agenda: Agenda commands. (line 65)
7641 * document structure: Document structure. (line 6)
7642 * DONE, final TODO keyword: Per file keywords. (line 26)
7643 * drawer, for properties: Property syntax. (line 6)
7644 * drawers: Drawers. (line 6)
7645 * dynamic blocks: Dynamic blocks. (line 6)
7646 * editing tables: Tables. (line 6)
7647 * editing, of table formulas: Editing and debugging formulas.
7649 * elisp links: External links. (line 6)
7650 * emphasized text: Export options. (line 26)
7651 * enhancing text: Enhancing text. (line 6)
7652 * evaluate time range: Creating timestamps. (line 48)
7653 * even, STARTUP keyword: In-buffer settings. (line 84)
7654 * exporting: Exporting. (line 6)
7655 * exporting agenda views <1>: Agenda commands. (line 233)
7656 * exporting agenda views: Exporting Agenda Views.
7658 * exporting, not: Comment lines. (line 6)
7659 * extended TODO keywords: TODO extensions. (line 6)
7660 * extension, third-party: Extensions. (line 6)
7661 * external archiving: Moving subtrees. (line 6)
7662 * external links: External links. (line 6)
7663 * external links, in HTML export: Links. (line 6)
7664 * faces, for TODO keywords: Faces for TODO keywords.
7666 * FAQ: Summary. (line 56)
7667 * feedback: Feedback. (line 6)
7668 * field formula: Field formulas. (line 6)
7669 * field references: References. (line 15)
7670 * file links: External links. (line 6)
7671 * file links, searching: Search options. (line 6)
7672 * file name completion: Handling links. (line 44)
7673 * files for agenda: Agenda files. (line 6)
7674 * files, adding to agenda list: Agenda files. (line 12)
7675 * files, selecting for publishing: Selecting files. (line 6)
7676 * fixed width: Enhancing text. (line 28)
7677 * fixed-width sections: Export options. (line 26)
7678 * folded, subtree visibility state: Visibility cycling. (line 10)
7679 * folding, sparse trees: Sparse trees. (line 6)
7680 * following links: Handling links. (line 59)
7681 * footnote.el <1>: Cooperation. (line 56)
7682 * footnote.el <2>: Footnotes. (line 6)
7683 * footnote.el: Conflicts. (line 35)
7684 * footnotes <1>: Export options. (line 26)
7685 * footnotes: Footnotes. (line 6)
7686 * format specifier: Formula syntax for Calc.
7688 * format, of links: Link format. (line 6)
7689 * formula debugging: Editing and debugging formulas.
7691 * formula editing: Editing and debugging formulas.
7693 * formula syntax, Calc: Formula syntax for Calc.
7695 * formula, for individual table field: Field formulas. (line 6)
7696 * formula, for table column: Column formulas. (line 6)
7697 * formula, in tables: Built-in table editor.
7699 * global cycling: Visibility cycling. (line 22)
7700 * global keybindings: Activation. (line 6)
7701 * global TODO list: Global TODO list. (line 6)
7702 * global visibility states: Visibility cycling. (line 22)
7703 * GNUS links: External links. (line 6)
7704 * grouping columns in tables: Column groups. (line 6)
7705 * hand-formatted lists: Enhancing text. (line 11)
7706 * headline levels: Export options. (line 26)
7707 * headline levels, for exporting <1>: ASCII export. (line 21)
7708 * headline levels, for exporting <2>: LaTeX export commands.
7710 * headline levels, for exporting: HTML Export commands.
7712 * headline navigation: Motion. (line 6)
7713 * headline tagging: Tags. (line 6)
7714 * headline, promotion and demotion: Structure editing. (line 6)
7715 * headlines: Headlines. (line 6)
7716 * hide text: Visibility cycling. (line 6)
7717 * hidestars, STARTUP keyword: In-buffer settings. (line 84)
7718 * hiding leading stars: Clean view. (line 6)
7719 * history: History and Acknowledgments.
7721 * horizontal rules, in exported files: Enhancing text. (line 18)
7722 * HTML export: HTML export. (line 6)
7723 * HTML, and orgtbl-mode: Translator functions.
7725 * hyperlinks: Hyperlinks. (line 6)
7726 * hyperlinks, adding new types: Adding hyperlink types.
7728 * iCalendar export: iCalendar export. (line 6)
7729 * images, inline in HTML: Images. (line 6)
7730 * in-buffer settings: In-buffer settings. (line 6)
7731 * inactive timestamp: Time stamps. (line 49)
7732 * index, of published pages: Project page index. (line 6)
7733 * Info links: External links. (line 6)
7734 * inheritance, of properties: Property searches. (line 6)
7735 * inheritance, of tags: Tag inheritance. (line 6)
7736 * inlining images in HTML: Images. (line 6)
7737 * inserting links: Handling links. (line 25)
7738 * installation: Installation. (line 6)
7739 * internal archiving: ARCHIVE tag. (line 6)
7740 * internal links: Internal links. (line 6)
7741 * internal links, in HTML export: Links. (line 6)
7742 * introduction: Introduction. (line 6)
7743 * italic text: Enhancing text. (line 15)
7744 * jumping, to headlines: Motion. (line 6)
7745 * keybindings, global: Activation. (line 6)
7746 * keyword options: Per file keywords. (line 6)
7747 * LaTeX export: LaTeX export. (line 6)
7748 * LaTeX fragments <1>: LaTeX fragments. (line 6)
7749 * LaTeX fragments: Export options. (line 26)
7750 * LaTeX fragments, export: Enhancing text. (line 21)
7751 * LaTeX fragments, preview: Processing LaTeX fragments.
7753 * LaTeX interpretation: Embedded LaTeX. (line 6)
7754 * LaTeX, and orgtbl-mode: A LaTeX example. (line 6)
7755 * level, require for tags match: Tag searches. (line 69)
7756 * linebreak preservation: Export options. (line 26)
7757 * linebreak, forced: Enhancing text. (line 35)
7758 * link abbreviations: Link abbreviations. (line 6)
7759 * link abbreviations, completion of: Completion. (line 6)
7760 * link completion: Handling links. (line 25)
7761 * link format: Link format. (line 6)
7762 * links, external: External links. (line 6)
7763 * links, finding next/previous: Handling links. (line 92)
7764 * links, handling: Handling links. (line 6)
7765 * links, in HTML export: Links. (line 6)
7766 * links, internal: Internal links. (line 6)
7767 * links, publishing: Publishing links. (line 6)
7768 * links, radio targets: Radio targets. (line 6)
7769 * links, returning to: Handling links. (line 86)
7770 * Lisp forms, as table formulas: Formula syntax for Lisp.
7772 * lists, hand-formatted: Enhancing text. (line 11)
7773 * lists, ordered: Plain lists. (line 6)
7774 * lists, plain: Plain lists. (line 6)
7775 * logdone, STARTUP keyword: In-buffer settings. (line 73)
7776 * logging, of progress: Progress logging. (line 6)
7777 * lognoteclock-out, STARTUP keyword: In-buffer settings. (line 73)
7778 * lognotedone, STARTUP keyword: In-buffer settings. (line 73)
7779 * lognotestate, STARTUP keyword: In-buffer settings. (line 73)
7780 * logrepeat, STARTUP keyword: In-buffer settings. (line 73)
7781 * maintainer: Feedback. (line 6)
7782 * mark ring: Handling links. (line 82)
7783 * marking characters, tables: Advanced features. (line 40)
7784 * matching, of properties: Matching tags and properties.
7786 * matching, of tags: Matching tags and properties.
7788 * matching, tags: Tags. (line 6)
7789 * math symbols: Math symbols. (line 6)
7790 * MH-E links: External links. (line 6)
7791 * minor mode for structure editing: orgstruct-mode. (line 6)
7792 * minor mode for tables: orgtbl-mode. (line 6)
7793 * mode, for calc: Formula syntax for Calc.
7795 * motion commands in agenda: Agenda commands. (line 19)
7796 * motion, between headlines: Motion. (line 6)
7797 * name, of column or field: References. (line 82)
7798 * named references: References. (line 82)
7799 * names as TODO keywords: TODO types. (line 6)
7800 * narrow columns in tables: Narrow columns. (line 6)
7801 * noalign, STARTUP keyword: In-buffer settings. (line 68)
7802 * nologging, STARTUP keyword: In-buffer settings. (line 73)
7803 * nologrepeat, STARTUP keyword: In-buffer settings. (line 73)
7804 * occur, command: Sparse trees. (line 6)
7805 * odd, STARTUP keyword: In-buffer settings. (line 84)
7806 * option keyword completion: Completion. (line 6)
7807 * options, for custom agenda views: Setting Options. (line 6)
7808 * options, for customization: Customization. (line 6)
7809 * options, for export: Export options. (line 6)
7810 * options, for publishing: Publishing options. (line 6)
7811 * ordered lists: Plain lists. (line 6)
7812 * org-agenda, command: Weekly/Daily agenda. (line 9)
7813 * org-blog.el: Extensions. (line 28)
7814 * org-mode, turning on: Activation. (line 22)
7815 * org-mouse.el: Extensions. (line 16)
7816 * org-publish-project-alist: Project alist. (line 6)
7817 * org-publish.el: Extensions. (line 8)
7818 * org2rem.el: Extensions. (line 36)
7819 * orgstruct-mode: orgstruct-mode. (line 6)
7820 * orgtbl-mode <1>: orgtbl-mode. (line 6)
7821 * orgtbl-mode: Tables in arbitrary syntax.
7823 * outline tree: Headlines. (line 6)
7824 * outline-mode: Outlines. (line 6)
7825 * outlines: Outlines. (line 6)
7826 * overview, global visibility state: Visibility cycling. (line 22)
7827 * overview, STARTUP keyword: In-buffer settings. (line 61)
7828 * packages, interaction with other: Interaction. (line 6)
7829 * pasting, of subtrees: Structure editing. (line 6)
7830 * per file keywords: Per file keywords. (line 6)
7831 * plain lists: Plain lists. (line 6)
7832 * plain text external links: External links. (line 43)
7833 * presentation, of agenda items: Presentation and sorting.
7835 * printing sparse trees: Sparse trees. (line 46)
7836 * priorities: Priorities. (line 6)
7837 * priorities, of agenda items: Sorting of agenda items.
7839 * progress logging: Progress logging. (line 6)
7840 * projects, for publishing: Project alist. (line 6)
7841 * promotion, of subtrees: Structure editing. (line 6)
7842 * properties: Properties and columns.
7844 * properties, API <1>: Using the property API.
7846 * properties, API: Property API. (line 6)
7847 * properties, column view: Defining columns. (line 6)
7848 * properties, inheritance: Property searches. (line 6)
7849 * properties, searching: Property searches. (line 6)
7850 * properties, special: Special properties. (line 6)
7851 * property syntax: Property syntax. (line 6)
7852 * publishing: Publishing. (line 6)
7853 * quoted HTML tags: Export options. (line 26)
7854 * radio tables: Radio tables. (line 6)
7855 * radio targets: Radio targets. (line 6)
7856 * range references: References. (line 60)
7857 * ranges, time: Time stamps. (line 6)
7858 * recomputing table fields: Updating the table. (line 6)
7859 * references: References. (line 6)
7860 * references, named: References. (line 82)
7861 * references, to fields: References. (line 15)
7862 * references, to ranges: References. (line 60)
7863 * region, active <1>: ASCII export. (line 9)
7864 * region, active <2>: Structure editing. (line 70)
7865 * region, active <3>: HTML Export commands.
7867 * region, active: Built-in table editor.
7869 * regular expressions, with tags search: Tag searches. (line 64)
7870 * remember.el <1>: Remember. (line 6)
7871 * remember.el: Cooperation. (line 33)
7872 * remote editing, from agenda: Agenda commands. (line 107)
7873 * remote editing, undo: Agenda commands. (line 108)
7874 * richer text: Enhancing text. (line 6)
7875 * RMAIL links: External links. (line 6)
7876 * SCHEDULED keyword: Deadlines and scheduling.
7878 * scheduling: Time stamps. (line 6)
7879 * Scripts, for agenda processing: Extracting Agenda Information for other programs.
7881 * search option in file links: Search options. (line 6)
7882 * search strings, custom: Custom searches. (line 6)
7883 * searching for tags: Tag searches. (line 6)
7884 * searching, of properties: Property searches. (line 6)
7885 * section-numbers: Export options. (line 26)
7886 * setting tags: Setting tags. (line 6)
7887 * SHELL links: External links. (line 6)
7888 * show all, command: Visibility cycling. (line 33)
7889 * show all, global visibility state: Visibility cycling. (line 22)
7890 * show hidden text: Visibility cycling. (line 6)
7891 * showall, STARTUP keyword: In-buffer settings. (line 61)
7892 * showstars, STARTUP keyword: In-buffer settings. (line 84)
7893 * sorting, of agenda items: Sorting of agenda items.
7895 * sparse tree, for deadlines: Inserting deadline/schedule.
7897 * sparse tree, for TODO: TODO basics. (line 38)
7898 * sparse tree, tag based: Tags. (line 6)
7899 * sparse trees: Sparse trees. (line 6)
7900 * special keywords: In-buffer settings. (line 6)
7901 * spreadsheet capabilities: The spreadsheet. (line 6)
7902 * statistics, for checkboxes: Checkboxes. (line 23)
7903 * storing links: Handling links. (line 9)
7904 * structure editing: Structure editing. (line 6)
7905 * structure of document: Document structure. (line 6)
7906 * sublevels, inclusion into tags match: Tag inheritance. (line 6)
7907 * sublevels, inclusion into todo list: Global TODO list. (line 34)
7908 * subscript: Subscripts and Superscripts.
7910 * subtree cycling: Visibility cycling. (line 10)
7911 * subtree visibility states: Visibility cycling. (line 10)
7912 * subtree, cut and paste: Structure editing. (line 6)
7913 * subtree, subtree visibility state: Visibility cycling. (line 10)
7914 * subtrees, cut and paste: Structure editing. (line 6)
7915 * summary: Summary. (line 6)
7916 * superscript: Subscripts and Superscripts.
7918 * syntax, of formulas: Formula syntax for Calc.
7920 * table editor, built-in: Built-in table editor.
7922 * table editor, table.el: Cooperation. (line 37)
7923 * table of contents: Export options. (line 26)
7924 * table.el: Cooperation. (line 34)
7925 * tables <1>: Tables. (line 6)
7926 * tables: Export options. (line 26)
7927 * tables, export: Enhancing text. (line 24)
7928 * tables, in other modes: Tables in arbitrary syntax.
7930 * tag completion: Completion. (line 6)
7931 * tag inheritance: Tag inheritance. (line 6)
7932 * tag searches: Tag searches. (line 6)
7933 * tags: Tags. (line 6)
7934 * tags view: Matching tags and properties.
7936 * tags, setting: Setting tags. (line 6)
7937 * targets, for links: Internal links. (line 6)
7938 * targets, radio: Radio targets. (line 6)
7939 * tasks, breaking down: Breaking down tasks. (line 6)
7940 * templates, for remember: Remember templates. (line 6)
7941 * TeX interpretation: Embedded LaTeX. (line 6)
7942 * TeX macros <1>: Math symbols. (line 6)
7943 * TeX macros: Export options. (line 26)
7944 * TeX macros, export: Enhancing text. (line 21)
7945 * TeX symbol completion: Completion. (line 6)
7946 * TeX-like syntax for sub- and superscripts: Export options. (line 26)
7947 * thanks: History and Acknowledgments.
7949 * time format, custom: Custom time format. (line 6)
7950 * time grid: Time-of-day specifications.
7952 * time info, in export: Export options. (line 26)
7953 * time stamps <1>: Timestamps. (line 6)
7954 * time stamps: Time stamps. (line 6)
7955 * time, reading in minibuffer: The date/time prompt.
7957 * time-of-day specification: Time-of-day specifications.
7959 * time-sorted view: Timeline. (line 6)
7960 * timeline, single file: Timeline. (line 6)
7961 * timerange: Time stamps. (line 40)
7962 * timestamp: Time stamps. (line 14)
7963 * timestamp, inactive: Time stamps. (line 49)
7964 * timestamp, with repeater interval: Time stamps. (line 24)
7965 * timestamps, creating: Creating timestamps. (line 6)
7966 * TODO items: TODO items. (line 6)
7967 * TODO keyword matching: Global TODO list. (line 17)
7968 * TODO keyword matching, with tags search: Tag searches. (line 41)
7969 * todo keyword sets: Multiple sets in one file.
7971 * TODO keywords completion: Completion. (line 6)
7972 * TODO list, global: Global TODO list. (line 6)
7973 * TODO types: TODO types. (line 6)
7974 * TODO workflow: Workflow states. (line 6)
7975 * transient-mark-mode <1>: Built-in table editor.
7977 * transient-mark-mode <2>: Structure editing. (line 70)
7978 * transient-mark-mode <3>: ASCII export. (line 9)
7979 * transient-mark-mode: HTML Export commands.
7981 * translator function: Translator functions.
7983 * trees, sparse: Sparse trees. (line 6)
7984 * trees, visibility: Visibility cycling. (line 6)
7985 * tty keybindings: TTY keys. (line 6)
7986 * types as TODO keywords: TODO types. (line 6)
7987 * underlined text: Enhancing text. (line 15)
7988 * undoing remote-editing events: Agenda commands. (line 108)
7989 * updating, table: Updating the table. (line 6)
7990 * URL links: External links. (line 6)
7991 * USENET links: External links. (line 6)
7992 * variables, for customization: Customization. (line 6)
7993 * vectors, in table calculations: Formula syntax for Calc.
7995 * visibility cycling: Visibility cycling. (line 6)
7996 * visibility cycling, drawers: Drawers. (line 6)
7997 * visible text, printing: Sparse trees. (line 46)
7998 * VM links: External links. (line 6)
7999 * WANDERLUST links: External links. (line 6)
8000 * weekly agenda: Weekly/Daily agenda. (line 6)
8001 * windmove.el: Conflicts. (line 32)
8002 * workflow states as TODO keywords: Workflow states. (line 6)
8003 * XEmacs: Installation. (line 6)
8004 * XOXO export: XOXO export. (line 6)
8007 File: org, Node: Key Index, Prev: Index, Up: Top
8015 * $: Agenda commands. (line 122)
8016 * ': CDLaTeX mode. (line 43)
8017 * +: Agenda commands. (line 145)
8018 * ,: Agenda commands. (line 137)
8019 * -: Agenda commands. (line 151)
8020 * .: Agenda commands. (line 99)
8021 * :: Agenda commands. (line 130)
8022 * < <1>: Using column view. (line 54)
8023 * <: The date/time prompt.
8025 * <left>: Agenda commands. (line 96)
8026 * <RET> <1>: Agenda commands. (line 39)
8027 * <RET> <2>: Setting tags. (line 76)
8028 * <RET> <3>: Built-in table editor.
8030 * <RET>: The date/time prompt.
8032 * <right>: Agenda commands. (line 91)
8033 * <SPC> <1>: Agenda commands. (line 28)
8034 * <SPC>: Setting tags. (line 73)
8035 * <TAB> <1>: Setting tags. (line 68)
8036 * <TAB> <2>: Visibility cycling. (line 10)
8037 * <TAB> <3>: CDLaTeX mode. (line 23)
8038 * <TAB> <4>: Plain lists. (line 41)
8039 * <TAB> <5>: Built-in table editor.
8041 * <TAB> <6>: Editing and debugging formulas.
8043 * <TAB>: Agenda commands. (line 33)
8044 * > <1>: Using column view. (line 54)
8045 * > <2>: Agenda commands. (line 173)
8046 * >: The date/time prompt.
8048 * ^: CDLaTeX mode. (line 33)
8049 * _: CDLaTeX mode. (line 33)
8050 * `: CDLaTeX mode. (line 39)
8051 * a <1>: Using column view. (line 43)
8052 * a: Agenda commands. (line 134)
8053 * b: Agenda commands. (line 49)
8054 * c: Agenda commands. (line 196)
8055 * C: Agenda commands. (line 216)
8056 * C-#: Advanced features. (line 9)
8057 * C-': Agenda files. (line 18)
8058 * C-,: Agenda files. (line 18)
8059 * C-<RET>: Structure editing. (line 18)
8060 * C-_: Agenda commands. (line 108)
8061 * C-c ! <1>: Footnotes. (line 14)
8062 * C-c !: Creating timestamps. (line 19)
8063 * C-c #: Checkboxes. (line 57)
8064 * C-c %: Handling links. (line 82)
8065 * C-c &: Handling links. (line 86)
8066 * C-c ': Editing and debugging formulas.
8068 * C-c *: Updating the table. (line 13)
8069 * C-c +: Built-in table editor.
8071 * C-c ,: Priorities. (line 18)
8072 * C-c - <1>: Built-in table editor.
8074 * C-c -: Plain lists. (line 88)
8075 * C-c .: Creating timestamps. (line 10)
8076 * C-c /: Sparse trees. (line 15)
8077 * C-c / p: Property searches. (line 23)
8078 * C-c / r: Sparse trees. (line 17)
8079 * C-c / T: Tag searches. (line 9)
8080 * C-c / t: TODO basics. (line 38)
8081 * C-c :: Enhancing text. (line 32)
8082 * C-c ;: Comment lines. (line 10)
8083 * C-c <: Creating timestamps. (line 23)
8084 * C-c <TAB>: Built-in table editor.
8086 * C-c = <1>: Column formulas. (line 26)
8087 * C-c =: Editing and debugging formulas.
8089 * C-c >: Creating timestamps. (line 27)
8090 * C-c ?: Editing and debugging formulas.
8092 * C-c [: Agenda files. (line 12)
8093 * C-c \: Tag searches. (line 9)
8094 * C-c ]: Agenda files. (line 15)
8095 * C-c ^ <1>: Built-in table editor.
8097 * C-c ^: Structure editing. (line 58)
8098 * C-c `: Built-in table editor.
8100 * C-c a !: Stuck projects. (line 14)
8101 * C-c a #: Stuck projects. (line 13)
8102 * C-c a a: Weekly/Daily agenda. (line 9)
8103 * C-c a C: Storing searches. (line 9)
8104 * C-c a e: Exporting Agenda Views.
8106 * C-c a L: Timeline. (line 10)
8107 * C-c a M: Matching tags and properties.
8109 * C-c a m <1>: Matching tags and properties.
8111 * C-c a m: Tag searches. (line 13)
8112 * C-c a M: Tag searches. (line 17)
8113 * C-c a T: Global TODO list. (line 14)
8114 * C-c a t <1>: TODO basics. (line 49)
8115 * C-c a t: Global TODO list. (line 9)
8116 * C-c C-a: Visibility cycling. (line 33)
8117 * C-c C-b: Motion. (line 15)
8118 * C-c C-c <1>: Clocking work time. (line 89)
8119 * C-c C-c <2>: Built-in table editor.
8121 * C-c C-c <3>: TODO basics. (line 30)
8122 * C-c C-c <4>: The very busy C-c C-c key.
8124 * C-c C-c <5>: Editing and debugging formulas.
8126 * C-c C-c <6>: Plain lists. (line 81)
8127 * C-c C-c <7>: Cooperation. (line 46)
8128 * C-c C-c <8>: Property syntax. (line 58)
8129 * C-c C-c <9>: Processing LaTeX fragments.
8131 * C-c C-c <10>: Checkboxes. (line 37)
8132 * C-c C-c <11>: Editing and debugging formulas.
8134 * C-c C-c: Setting tags. (line 10)
8135 * C-c C-d <1>: Inserting deadline/schedule.
8137 * C-c C-d: Agenda commands. (line 158)
8138 * C-c C-e: Exporting. (line 20)
8139 * C-c C-e a: ASCII export. (line 9)
8140 * C-c C-e b: HTML Export commands.
8142 * C-c C-e c: iCalendar export. (line 21)
8143 * C-c C-e h: HTML Export commands.
8145 * C-c C-e H: HTML Export commands.
8147 * C-c C-e I: iCalendar export. (line 16)
8148 * C-c C-e i: iCalendar export. (line 14)
8149 * C-c C-e l: LaTeX export commands.
8151 * C-c C-e L: LaTeX export commands.
8153 * C-c C-e R: HTML Export commands.
8155 * C-c C-e t: Export options. (line 13)
8156 * C-c C-e v <1>: Sparse trees. (line 46)
8157 * C-c C-e v: XOXO export. (line 11)
8158 * C-c C-e v a: ASCII export. (line 16)
8159 * C-c C-e v b: HTML Export commands.
8161 * C-c C-e v H: HTML Export commands.
8163 * C-c C-e v h: HTML Export commands.
8165 * C-c C-e v l: LaTeX export commands.
8167 * C-c C-e v L: LaTeX export commands.
8169 * C-c C-e v R: HTML Export commands.
8171 * C-c C-e x: XOXO export. (line 10)
8172 * C-c C-f: Motion. (line 12)
8173 * C-c C-j: Motion. (line 21)
8174 * C-c C-l: Handling links. (line 25)
8175 * C-c C-n: Motion. (line 8)
8176 * C-c C-o <1>: Creating timestamps. (line 31)
8177 * C-c C-o: Handling links. (line 59)
8178 * C-c C-p: Motion. (line 9)
8179 * C-c C-q <1>: Built-in table editor.
8181 * C-c C-q: Editing and debugging formulas.
8183 * C-c C-r <1>: Editing and debugging formulas.
8185 * C-c C-r: Visibility cycling. (line 34)
8186 * C-c C-s <1>: Agenda commands. (line 155)
8187 * C-c C-s: Inserting deadline/schedule.
8189 * C-c C-t <1>: Clocking work time. (line 30)
8190 * C-c C-t: TODO basics. (line 13)
8191 * C-c C-u: Motion. (line 18)
8192 * C-c C-v: TODO basics. (line 38)
8193 * C-c C-w: Inserting deadline/schedule.
8195 * C-c C-x b: Visibility cycling. (line 41)
8196 * C-c C-x C-a: ARCHIVE tag. (line 28)
8197 * C-c C-x C-b: Checkboxes. (line 39)
8198 * C-c C-x C-c <1>: Agenda commands. (line 223)
8199 * C-c C-x C-c: Using column view. (line 9)
8200 * C-c C-x C-d: Clocking work time. (line 42)
8201 * C-c C-x C-i: Clocking work time. (line 12)
8202 * C-c C-x C-j: Clocking work time. (line 38)
8203 * C-c C-x C-k: Structure editing. (line 43)
8204 * C-c C-x C-l: Processing LaTeX fragments.
8206 * C-c C-x C-n: Handling links. (line 92)
8207 * C-c C-x C-o: Clocking work time. (line 17)
8208 * C-c C-x C-p: Handling links. (line 92)
8209 * C-c C-x C-r: Clocking work time. (line 50)
8210 * C-c C-x C-s: Moving subtrees. (line 10)
8211 * C-c C-x C-t: Custom time format. (line 12)
8212 * C-c C-x C-u <1>: Clocking work time. (line 91)
8213 * C-c C-x C-u: Dynamic blocks. (line 21)
8214 * C-c C-x C-w <1>: Built-in table editor.
8216 * C-c C-x C-w: Structure editing. (line 43)
8217 * C-c C-x C-x: Clocking work time. (line 34)
8218 * C-c C-x C-y <1>: Structure editing. (line 52)
8219 * C-c C-x C-y: Built-in table editor.
8221 * C-c C-x M-w <1>: Structure editing. (line 48)
8222 * C-c C-x M-w: Built-in table editor.
8224 * C-c C-x p: Property syntax. (line 49)
8225 * C-c C-y <1>: Creating timestamps. (line 48)
8226 * C-c C-y: Clocking work time. (line 25)
8227 * C-c l: Handling links. (line 9)
8228 * C-c { <1>: Editing and debugging formulas.
8230 * C-c {: CDLaTeX mode. (line 21)
8231 * C-c |: Built-in table editor.
8233 * C-c }: Editing and debugging formulas.
8235 * C-c ~: Cooperation. (line 48)
8236 * C-k: Agenda commands. (line 116)
8237 * C-S-<left>: Multiple sets in one file.
8239 * C-S-<right>: Multiple sets in one file.
8241 * C-TAB: ARCHIVE tag. (line 38)
8242 * C-u C-c *: Updating the table. (line 16)
8243 * C-u C-c .: Creating timestamps. (line 14)
8244 * C-u C-c = <1>: Editing and debugging formulas.
8246 * C-u C-c =: Field formulas. (line 24)
8247 * C-u C-c C-c: Updating the table. (line 19)
8248 * C-u C-c C-l: Handling links. (line 44)
8249 * C-u C-c C-t: TODO basics. (line 22)
8250 * C-u C-c C-x C-a: ARCHIVE tag. (line 31)
8251 * C-u C-c C-x C-s: Moving subtrees. (line 14)
8252 * C-u C-c C-x C-u <1>: Clocking work time. (line 93)
8253 * C-u C-c C-x C-u: Dynamic blocks. (line 22)
8254 * C-u C-u C-c *: Updating the table. (line 22)
8255 * C-u C-u C-c =: Editing and debugging formulas.
8257 * C-u C-u C-c C-c: Updating the table. (line 22)
8258 * C-x C-s <1>: Agenda commands. (line 87)
8259 * C-x C-s: Editing and debugging formulas.
8261 * C-x C-w <1>: Exporting Agenda Views.
8263 * C-x C-w: Agenda commands. (line 232)
8264 * D: Agenda commands. (line 72)
8265 * d: Agenda commands. (line 66)
8266 * e: Using column view. (line 33)
8267 * f: Agenda commands. (line 42)
8268 * g: Agenda commands. (line 76)
8269 * H: Agenda commands. (line 220)
8270 * i: Agenda commands. (line 201)
8271 * I: Agenda commands. (line 178)
8272 * J: Agenda commands. (line 190)
8273 * l: Agenda commands. (line 55)
8274 * L: Agenda commands. (line 30)
8275 * M: Agenda commands. (line 207)
8276 * m: Agenda commands. (line 66)
8277 * M-<down> <1>: Editing and debugging formulas.
8279 * M-<down>: Built-in table editor.
8281 * M-<left> <1>: Structure editing. (line 25)
8282 * M-<left>: Built-in table editor.
8284 * M-<RET> <1>: Structure editing. (line 6)
8285 * M-<RET>: Plain lists. (line 49)
8286 * M-<right> <1>: Built-in table editor.
8288 * M-<right>: Structure editing. (line 28)
8289 * M-<TAB> <1>: Per file keywords. (line 23)
8290 * M-<TAB> <2>: Property syntax. (line 46)
8291 * M-<TAB> <3>: Completion. (line 10)
8292 * M-<TAB> <4>: Setting tags. (line 6)
8293 * M-<TAB>: Editing and debugging formulas.
8295 * M-<up> <1>: Built-in table editor.
8297 * M-<up>: Editing and debugging formulas.
8299 * M-S-<down> <1>: Structure editing. (line 40)
8300 * M-S-<down> <2>: Editing and debugging formulas.
8302 * M-S-<down> <3>: Built-in table editor.
8304 * M-S-<down>: Plain lists. (line 66)
8305 * M-S-<left> <1>: Built-in table editor.
8307 * M-S-<left> <2>: The date/time prompt.
8309 * M-S-<left> <3>: Plain lists. (line 72)
8310 * M-S-<left>: Structure editing. (line 31)
8311 * M-S-<RET> <1>: Checkboxes. (line 54)
8312 * M-S-<RET> <2>: Structure editing. (line 22)
8313 * M-S-<RET>: Plain lists. (line 59)
8314 * M-S-<right> <1>: The date/time prompt.
8316 * M-S-<right> <2>: Built-in table editor.
8318 * M-S-<right> <3>: Structure editing. (line 34)
8319 * M-S-<right>: Plain lists. (line 72)
8320 * M-S-<up> <1>: Built-in table editor.
8322 * M-S-<up> <2>: Editing and debugging formulas.
8324 * M-S-<up> <3>: Structure editing. (line 37)
8325 * M-S-<up>: Plain lists. (line 66)
8326 * mouse-1 <1>: Handling links. (line 73)
8327 * mouse-1 <2>: Agenda commands. (line 33)
8328 * mouse-1: The date/time prompt.
8330 * mouse-2 <1>: Agenda commands. (line 33)
8331 * mouse-2: Handling links. (line 73)
8332 * mouse-3 <1>: Agenda commands. (line 28)
8333 * mouse-3: Handling links. (line 78)
8334 * n <1>: Agenda commands. (line 19)
8335 * n: Using column view. (line 30)
8336 * o: Agenda commands. (line 65)
8337 * O: Agenda commands. (line 182)
8338 * p <1>: Agenda commands. (line 20)
8339 * p: Using column view. (line 30)
8340 * P: Agenda commands. (line 142)
8341 * q <1>: Using column view. (line 17)
8342 * q: Agenda commands. (line 243)
8343 * r <1>: Agenda commands. (line 80)
8344 * r: Global TODO list. (line 22)
8345 * S: Agenda commands. (line 211)
8346 * s: Agenda commands. (line 87)
8347 * S-<down> <1>: Editing and debugging formulas.
8349 * S-<down> <2>: Creating timestamps. (line 40)
8350 * S-<down> <3>: The date/time prompt.
8352 * S-<down> <4>: Agenda commands. (line 151)
8353 * S-<down> <5>: Priorities. (line 23)
8354 * S-<down>: Plain lists. (line 62)
8355 * S-<left> <1>: Creating timestamps. (line 35)
8356 * S-<left> <2>: The date/time prompt.
8358 * S-<left> <3>: Editing and debugging formulas.
8360 * S-<left> <4>: Multiple sets in one file.
8362 * S-<left> <5>: Using column view. (line 26)
8363 * S-<left> <6>: Property syntax. (line 66)
8364 * S-<left> <7>: Agenda commands. (line 169)
8365 * S-<left>: TODO basics. (line 26)
8366 * S-<RET>: Built-in table editor.
8368 * S-<right> <1>: Using column view. (line 26)
8369 * S-<right> <2>: Agenda commands. (line 161)
8370 * S-<right> <3>: Multiple sets in one file.
8372 * S-<right> <4>: TODO basics. (line 26)
8373 * S-<right> <5>: The date/time prompt.
8375 * S-<right> <6>: Creating timestamps. (line 35)
8376 * S-<right> <7>: Property syntax. (line 66)
8377 * S-<right>: Editing and debugging formulas.
8379 * S-<TAB> <1>: Built-in table editor.
8381 * S-<TAB>: Visibility cycling. (line 22)
8382 * S-<up> <1>: The date/time prompt.
8384 * S-<up> <2>: Priorities. (line 23)
8385 * S-<up> <3>: Editing and debugging formulas.
8387 * S-<up> <4>: Plain lists. (line 62)
8388 * S-<up> <5>: Agenda commands. (line 145)
8389 * S-<up>: Creating timestamps. (line 40)
8390 * S-M-<left>: Using column view. (line 58)
8391 * S-M-<RET>: TODO basics. (line 57)
8392 * S-M-<right>: Using column view. (line 55)
8393 * T: Agenda commands. (line 125)
8394 * t: Agenda commands. (line 112)
8395 * v: Using column view. (line 39)
8396 * w: Agenda commands. (line 66)
8397 * X: Agenda commands. (line 185)
8398 * x: Agenda commands. (line 244)
8399 * y: Agenda commands. (line 66)
8405 Node: Introduction
\x7f13081
8406 Node: Summary
\x7f13496
8407 Node: Installation
\x7f16623
8408 Node: Activation
\x7f18001
8409 Node: Feedback
\x7f19238
8410 Node: Document structure
\x7f21307
8411 Node: Outlines
\x7f22199
8412 Node: Headlines
\x7f22864
8413 Ref: Headlines-Footnote-1
\x7f23868
8414 Node: Visibility cycling
\x7f23979
8415 Ref: Visibility cycling-Footnote-1
\x7f26189
8416 Ref: Visibility cycling-Footnote-2
\x7f26247
8417 Ref: Visibility cycling-Footnote-3
\x7f26297
8418 Node: Motion
\x7f26567
8419 Node: Structure editing
\x7f27521
8420 Node: Archiving
\x7f30616
8421 Node: ARCHIVE tag
\x7f31174
8422 Node: Moving subtrees
\x7f32967
8423 Ref: Moving subtrees-Footnote-1
\x7f34514
8424 Node: Sparse trees
\x7f34801
8425 Ref: Sparse trees-Footnote-1
\x7f37073
8426 Ref: Sparse trees-Footnote-2
\x7f37255
8427 Node: Plain lists
\x7f37370
8428 Ref: Plain lists-Footnote-1
\x7f41567
8429 Ref: Plain lists-Footnote-2
\x7f41925
8430 Node: Drawers
\x7f42106
8431 Node: orgstruct-mode
\x7f42944
8432 Node: Tables
\x7f43844
8433 Node: Built-in table editor
\x7f44425
8434 Node: Narrow columns
\x7f51831
8435 Ref: Narrow columns-Footnote-1
\x7f53766
8436 Node: Column groups
\x7f53812
8437 Node: orgtbl-mode
\x7f55345
8438 Node: The spreadsheet
\x7f56148
8439 Node: References
\x7f57235
8440 Ref: References-Footnote-1
\x7f61699
8441 Node: Formula syntax for Calc
\x7f61988
8442 Node: Formula syntax for Lisp
\x7f64445
8443 Node: Field formulas
\x7f66163
8444 Node: Column formulas
\x7f67471
8445 Node: Editing and debugging formulas
\x7f69070
8446 Node: Updating the table
\x7f73223
8447 Node: Advanced features
\x7f74276
8448 Node: Hyperlinks
\x7f78801
8449 Node: Link format
\x7f79579
8450 Node: Internal links
\x7f80872
8451 Ref: Internal links-Footnote-1
\x7f82797
8452 Node: Radio targets
\x7f82932
8453 Node: External links
\x7f83632
8454 Node: Handling links
\x7f86036
8455 Ref: Handling links-Footnote-1
\x7f91352
8456 Ref: Handling links-Footnote-2
\x7f91589
8457 Node: Using links outside Org-mode
\x7f91663
8458 Node: Link abbreviations
\x7f92173
8459 Node: Search options
\x7f93866
8460 Ref: Search options-Footnote-1
\x7f95646
8461 Node: Custom searches
\x7f95727
8462 Node: TODO items
\x7f96758
8463 Node: TODO basics
\x7f97796
8464 Node: TODO extensions
\x7f100011
8465 Node: Workflow states
\x7f100955
8466 Ref: Workflow states-Footnote-1
\x7f102130
8467 Node: TODO types
\x7f102223
8468 Ref: TODO types-Footnote-1
\x7f103806
8469 Node: Multiple sets in one file
\x7f103888
8470 Node: Fast access to TODO states
\x7f105508
8471 Node: Per file keywords
\x7f106651
8472 Ref: Per file keywords-Footnote-1
\x7f107953
8473 Node: Faces for TODO keywords
\x7f108154
8474 Node: Progress logging
\x7f108860
8475 Node: Closing items
\x7f109291
8476 Ref: Closing items-Footnote-1
\x7f110225
8477 Ref: Closing items-Footnote-2
\x7f110430
8478 Node: Tracking TODO state changes
\x7f110503
8479 Ref: Tracking TODO state changes-Footnote-1
\x7f111688
8480 Node: Priorities
\x7f111763
8481 Ref: Priorities-Footnote-1
\x7f113413
8482 Node: Breaking down tasks
\x7f113483
8483 Ref: Breaking down tasks-Footnote-1
\x7f114003
8484 Node: Checkboxes
\x7f114099
8485 Node: Tags
\x7f116948
8486 Node: Tag inheritance
\x7f117720
8487 Node: Setting tags
\x7f118657
8488 Ref: Setting tags-Footnote-1
\x7f123180
8489 Ref: Setting tags-Footnote-2
\x7f123292
8490 Node: Tag searches
\x7f123375
8491 Node: Properties and columns
\x7f126102
8492 Node: Property syntax
\x7f127207
8493 Node: Special properties
\x7f129897
8494 Node: Property searches
\x7f130813
8495 Node: Column view
\x7f132080
8496 Node: Defining columns
\x7f133247
8497 Node: Scope of column definitions
\x7f133645
8498 Node: Column attributes
\x7f134567
8499 Node: Using column view
\x7f136815
8500 Node: Property API
\x7f138802
8501 Node: Timestamps
\x7f139156
8502 Node: Time stamps
\x7f139567
8503 Ref: Time stamps-Footnote-1
\x7f141921
8504 Node: Creating timestamps
\x7f142037
8505 Node: The date/time prompt
\x7f144111
8506 Ref: The date/time prompt-Footnote-1
\x7f146717
8507 Node: Custom time format
\x7f146823
8508 Node: Deadlines and scheduling
\x7f148515
8509 Ref: Deadlines and scheduling-Footnote-1
\x7f150588
8510 Node: Inserting deadline/schedule
\x7f150743
8511 Node: Repeated tasks
\x7f151861
8512 Ref: Repeated tasks-Footnote-1
\x7f153539
8513 Node: Clocking work time
\x7f153660
8514 Ref: Clocking work time-Footnote-1
\x7f158507
8515 Ref: Clocking work time-Footnote-2
\x7f158585
8516 Node: Remember
\x7f158711
8517 Node: Setting up remember
\x7f159590
8518 Node: Remember templates
\x7f160193
8519 Ref: Remember templates-Footnote-1
\x7f163754
8520 Ref: Remember templates-Footnote-2
\x7f163937
8521 Node: Storing notes
\x7f164035
8522 Ref: Storing notes-Footnote-1
\x7f166514
8523 Node: Agenda views
\x7f166616
8524 Node: Agenda files
\x7f168567
8525 Ref: Agenda files-Footnote-1
\x7f169535
8526 Ref: Agenda files-Footnote-2
\x7f169684
8527 Node: Agenda dispatcher
\x7f169877
8528 Node: Built-in agenda views
\x7f171880
8529 Node: Weekly/Daily agenda
\x7f172462
8530 Node: Global TODO list
\x7f175799
8531 Node: Matching tags and properties
\x7f178079
8532 Node: Timeline
\x7f179170
8533 Node: Stuck projects
\x7f179844
8534 Node: Presentation and sorting
\x7f181697
8535 Node: Categories
\x7f182490
8536 Ref: Categories-Footnote-1
\x7f183201
8537 Node: Time-of-day specifications
\x7f183521
8538 Node: Sorting of agenda items
\x7f185494
8539 Node: Agenda commands
\x7f186778
8540 Node: Custom agenda views
\x7f194241
8541 Node: Storing searches
\x7f194962
8542 Node: Block agenda
\x7f196876
8543 Node: Setting Options
\x7f198108
8544 Node: Exporting Agenda Views
\x7f200849
8545 Ref: Exporting Agenda Views-Footnote-1
\x7f205135
8546 Ref: Exporting Agenda Views-Footnote-2
\x7f205192
8547 Node: Extracting Agenda Information for other programs
\x7f205378
8548 Node: Embedded LaTeX
\x7f209506
8549 Ref: Embedded LaTeX-Footnote-1
\x7f210600
8550 Node: Math symbols
\x7f210790
8551 Node: Subscripts and Superscripts
\x7f211557
8552 Node: LaTeX fragments
\x7f212403
8553 Ref: LaTeX fragments-Footnote-1
\x7f214636
8554 Ref: LaTeX fragments-Footnote-2
\x7f214897
8555 Node: Processing LaTeX fragments
\x7f215031
8556 Node: CDLaTeX mode
\x7f215979
8557 Ref: CDLaTeX mode-Footnote-1
\x7f218465
8558 Node: Exporting
\x7f218613
8559 Node: ASCII export
\x7f220080
8560 Node: HTML export
\x7f221581
8561 Node: HTML Export commands
\x7f222207
8562 Node: Quoting HTML tags
\x7f223994
8563 Node: Links
\x7f224629
8564 Node: Images
\x7f225326
8565 Ref: Images-Footnote-1
\x7f226197
8566 Node: CSS support
\x7f226258
8567 Ref: CSS support-Footnote-1
\x7f227577
8568 Node: LaTeX export
\x7f227690
8569 Node: LaTeX export commands
\x7f228014
8570 Node: Quoting LaTeX code
\x7f229176
8571 Node: XOXO export
\x7f229681
8572 Node: iCalendar export
\x7f230121
8573 Node: Text interpretation
\x7f231590
8574 Node: Comment lines
\x7f232181
8575 Node: Initial text
\x7f232576
8576 Node: Footnotes
\x7f234245
8577 Node: Enhancing text
\x7f235036
8578 Ref: Enhancing text-Footnote-1
\x7f236905
8579 Node: Export options
\x7f236995
8580 Node: Publishing
\x7f239394
8581 Ref: Publishing-Footnote-1
\x7f240355
8582 Ref: Publishing-Footnote-2
\x7f240499
8583 Node: Configuration
\x7f240650
8584 Node: Project alist
\x7f241368
8585 Node: Sources and destinations
\x7f242434
8586 Node: Selecting files
\x7f243164
8587 Node: Publishing action
\x7f243912
8588 Node: Publishing options
\x7f245246
8589 Node: Publishing links
\x7f247621
8590 Node: Project page index
\x7f249134
8591 Node: Sample configuration
\x7f249912
8592 Node: Simple example
\x7f250404
8593 Node: Complex example
\x7f251077
8594 Node: Triggering publication
\x7f253153
8595 Node: Miscellaneous
\x7f253838
8596 Node: Completion
\x7f254472
8597 Node: Customization
\x7f256142
8598 Node: In-buffer settings
\x7f256725
8599 Node: The very busy C-c C-c key
\x7f262287
8600 Node: Clean view
\x7f264142
8601 Node: TTY keys
\x7f266719
8602 Node: Interaction
\x7f268329
8603 Node: Cooperation
\x7f268726
8604 Node: Conflicts
\x7f271602
8605 Node: Bugs
\x7f273605
8606 Node: Extensions and Hacking
\x7f275101
8607 Node: Extensions
\x7f275826
8608 Node: Adding hyperlink types
\x7f278088
8609 Node: Tables in arbitrary syntax
\x7f281750
8610 Node: Radio tables
\x7f282839
8611 Node: A LaTeX example
\x7f285342
8612 Ref: A LaTeX example-Footnote-1
\x7f288988
8613 Ref: A LaTeX example-Footnote-2
\x7f289136
8614 Node: Translator functions
\x7f289571
8615 Ref: Translator functions-Footnote-1
\x7f292680
8616 Node: Dynamic blocks
\x7f292768
8617 Node: Special agenda views
\x7f294740
8618 Node: Using the property API
\x7f297985
8619 Node: History and Acknowledgments
\x7f299466
8620 Node: Index
\x7f306028
8621 Node: Key Index
\x7f341097