1 This is org, produced by makeinfo version 4.8 from org.texi.
5 * Org Mode: (org). Outline-based notes management and organizer
8 This manual is for Org-mode (version 5.08).
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.08).
32 Copyright (C) 2004, 2005, 2006, 2007 Free Software Foundation
34 Permission is granted to copy, distribute and/or modify this
35 document under the terms of the GNU Free Documentation License,
36 Version 1.1 or any later version published by the Free Software
37 Foundation; with no Invariant Sections, with the Front-Cover texts
38 being "A GNU Manual," and with the Back-Cover Texts as in (a)
39 below. A copy of the license is included in the section entitled
40 "GNU Free Documentation License."
42 (a) The FSF's Back-Cover Text is: "You have freedom to copy and
43 modify this GNU Manual, like GNU software. Copies published by
44 the Free Software Foundation raise funds for GNU development."
48 * Introduction:: Getting started
49 * Document structure:: A tree works like your brain
50 * Tables:: Pure magic for quick formatting
51 * Hyperlinks:: Notes in context
52 * TODO items:: Every tree branch can be a TODO item
53 * Tags:: Tagging headlines and matching sets of tags
54 * Properties and columns::
55 * Timestamps:: Assign date and time to items
56 * Agenda views:: Collecting information into views
57 * Embedded LaTeX:: LaTeX fragments and formulas
58 * Exporting:: Sharing and publishing of notes
59 * Publishing:: Create a web site of linked Org-mode files
60 * Miscellaneous:: All the rest which did not fit elsewhere
61 * Extensions and Hacking:: It is possible to write add-on code
62 * History and Acknowledgments:: How Org-mode came into being
63 * Index:: The fast road to specific information
64 * Key Index:: Key bindings and where they are described
66 --- The Detailed Node Listing ---
70 * Summary:: Brief summary of what Org-mode does
71 * Installation:: How to install a downloaded version of Org-mode
72 * Activation:: How to activate Org-mode for certain buffers.
73 * Feedback:: Bug reports, ideas, patches etc.
77 * Outlines:: Org-mode is based on outline-mode
78 * Headlines:: How to typeset org-tree headlines
79 * Visibility cycling:: Show and hide, much simplified
80 * Motion:: Jumping to other headlines
81 * Structure editing:: Changing sequence and level of headlines
82 * Archiving:: Move done task trees to a different place
83 * Sparse trees:: Matches embedded in context
84 * Plain lists:: Additional structure within an entry
85 * Drawers:: Tucking stuff away
86 * orgstruct-mode:: Structure editing outside Org-mode
90 * ARCHIVE tag:: Marking a tree as inactive
91 * Moving subtrees:: Moving a tree to an archive file
95 * Built-in table editor:: Simple tables
96 * Narrow columns:: Stop wasting space in tables
97 * Column groups:: Grouping to trigger vertical lines
98 * orgtbl-mode:: The table editor as minor mode
99 * The spreadsheet:: The table editor has spreadsheet capabilities.
103 * References:: How to refer to another field or range
104 * Formula syntax for Calc:: Using Calc to compute stuff
105 * Formula syntax for Lisp:: Writing formulas in Emacs Lisp
106 * Field formulas:: Formulas valid for a single field
107 * Column formulas:: Formulas valid for an entire column
108 * Editing and debugging formulas:: Fixing formulas
109 * Updating the table:: Recomputing all dependent fields
110 * Advanced features:: Field names, parameters and automatic recalc
114 * Link format:: How links in Org-mode are formatted
115 * Internal links:: Links to other places in the current file
116 * External links:: URL-like links to the world
117 * Handling links:: Creating, inserting and following
118 * Using links outside Org-mode:: Linking from my C source code?
119 * Link abbreviations:: Shortcuts for writing complex links
120 * Search options:: Linking to a specific location
121 * Custom searches:: When the default search is not enough
122 * Remember:: Org-trees store quick notes
126 * Radio targets:: Make targets trigger links in plain text.
130 * Setting up remember:: Some code for .emacs to get things going
131 * Remember templates:: Define the outline of different note types
132 * Storing notes:: Directly get the note to where it belongs
136 * TODO basics:: Marking and displaying TODO entries
137 * TODO extensions:: Workflow and assignments
138 * Priorities:: Some things are more important than others
139 * Breaking down tasks:: Splitting a task into manageable pieces
140 * Checkboxes:: Tick-off lists
142 Extended use of TODO keywords
144 * Workflow states:: From TODO to DONE in steps
145 * TODO types:: I do this, Fred the rest
146 * Multiple sets in one file:: Mixing it all, and still finding your way
147 * Per file keywords:: Different files, different requirements
151 * Tag inheritance:: Tags use the tree structure of the outline
152 * Setting tags:: How to assign tags to a headline
153 * Tag searches:: Searching for combinations of tags
155 Properties and Columns
157 * Property syntax:: How properties are spelled out
158 * Special properties:: Access to other Org-mode features
159 * Property searches:: Matching property values
160 * Column view:: Tabular viewing and editing
161 * Property API:: Properties for Lisp programmers
165 * Defining columns:: The COLUMNS format property
166 * Using column view:: How to create and use column view
170 * Scope of column definitions:: Where defined, where valid?
171 * Column attributes:: Appearance and content of a column
175 * Time stamps:: Assigning a time to a tree entry
176 * Creating timestamps:: Commands which insert timestamps
177 * Deadlines and scheduling:: Planning your work
178 * Progress logging:: Documenting when what work was done.
182 * The date/time prompt:: How org-mode helps you entering date and time
183 * Custom time format:: Making dates look differently
185 Deadlines and Scheduling
187 * Inserting deadline/schedule:: Planning items
188 * Repeated tasks:: Items that show up again and again
192 * Closing items:: When was this entry marked DONE?
193 * Tracking TODO state changes:: When did the status change?
194 * Clocking work time:: When exactly did you work on this item?
198 * Agenda files:: Files being searched for agenda information
199 * Agenda dispatcher:: Keyboard access to agenda views
200 * Built-in agenda views:: What is available out of the box?
201 * Presentation and sorting:: How agenda items are prepared for display
202 * Agenda commands:: Remote editing of org trees
203 * Custom agenda views:: Defining special searches and views
205 The built-in agenda views
207 * Weekly/Daily agenda:: The calendar page with current tasks
208 * Global TODO list:: All unfinished action items
209 * Matching tags and properties:: Structured information with fine-tuned search
210 * Timeline:: Time-sorted view for single file
211 * Stuck projects:: Find projects you need to review
213 Presentation and sorting
215 * Categories:: Not all tasks are equal
216 * Time-of-day specifications:: How the agenda knows the time
217 * Sorting of agenda items:: The order of things
221 * Storing searches:: Type once, use often
222 * Block agenda:: All the stuff you need in a single buffer
223 * Setting Options:: Changing the rules
224 * Exporting Agenda Views:: Writing agendas to files.
225 * Extracting Agenda Information for other programs::
229 * Math symbols:: TeX macros for symbols and Greek letters
230 * Subscripts and Superscripts:: Simple syntax for raising/lowering text
231 * LaTeX fragments:: Complex formulas made easy
232 * Processing LaTeX fragments:: Previewing LaTeX processing
233 * CDLaTeX mode:: Speed up entering of formulas
237 * ASCII export:: Exporting to plain ASCII
238 * HTML export:: Exporting to HTML
239 * LaTeX export:: Exporting to LaTeX
240 * XOXO export:: Exporting to XOXO
241 * iCalendar export:: Exporting in iCalendar format
242 * Text interpretation:: How the exporter looks at the file
246 * HTML Export commands:: How to invoke LaTeX export
247 * Quoting HTML tags:: Using direct HTML in Org-mode
248 * Links:: Transformation of links for HTML
249 * Images:: How to include images
250 * CSS support:: Changing the appearence of the output
254 * LaTeX export commands:: How to invoke LaTeX export
255 * Quoting LaTeX code:: Incorporating literal LaTeX code
257 Text interpretation by the exporter
259 * Comment lines:: Some lines will not be exported
260 * Initial text:: Text before the first headline
261 * Footnotes:: Numbers like [1]
262 * Enhancing text:: Subscripts, symbols and more
263 * Export options:: How to influence the export settings
267 * Configuration:: Defining projects
268 * Sample configuration:: Example projects
269 * Triggering publication:: Publication commands
273 * Project alist:: The central configuration variable
274 * Sources and destinations:: From here to there
275 * Selecting files:: What files are part of the project?
276 * Publishing action:: Setting the function doing the publishing
277 * Publishing options:: Tweaking HTML export
278 * Publishing links:: Which links keep working after publishing?
279 * Project page index:: Publishing a list of project files
283 * Simple example:: One-component publishing
284 * Complex example:: A multi-component publishing example
288 * Completion:: M-TAB knows what you need
289 * Customization:: Adapting Org-mode to your taste
290 * In-buffer settings:: Overview of the #+KEYWORDS
291 * The very busy C-c C-c key:: When in doubt, press C-c C-c
292 * Clean view:: Getting rid of leading stars in the outline
293 * TTY keys:: Using Org-mode on a tty
294 * Interaction:: Other Emacs packages
295 * Bugs:: Things which do not work perfectly
297 Interaction with other packages
299 * Cooperation:: Packages Org-mode cooperates with
300 * Conflicts:: Packages that lead to conflicts
302 Extensions, Hooks and Hacking
304 * Extensions:: Existing 3rd-part extensions
305 * Adding hyperlink types:: New custom link types
306 * Tables in arbitrary syntax:: Orgtbl for LaTeX and other programs
307 * Dynamic blocks:: Automatically filled blocks
308 * Special agenda views:: Customized views
309 * Using the property API:: Writing programs that use entry properties
311 Tables in arbitrary syntax
313 * Radio tables:: Sending and receiving
314 * A LaTeX example:: Step by step, almost a tutorial
315 * Translator functions:: Copy and modify
318 File: org, Node: Introduction, Next: Document structure, Prev: Top, Up: Top
325 * Summary:: Brief summary of what Org-mode does
326 * Installation:: How to install a downloaded version of Org-mode
327 * Activation:: How to activate Org-mode for certain buffers.
328 * Feedback:: Bug reports, ideas, patches etc.
331 File: org, Node: Summary, Next: Installation, Prev: Introduction, Up: Introduction
336 Org-mode is a mode for keeping notes, maintaining TODO lists, and doing
337 project planning with a fast and effective plain-text system.
339 Org-mode develops organizational tasks around NOTES files that
340 contain lists or information about projects as plain text. Org-mode is
341 implemented on top of outline-mode, which makes it possible to keep the
342 content of large files well structured. Visibility cycling and
343 structure editing help to work with the tree. Tables are easily created
344 with a built-in table editor. Org-mode supports TODO items, deadlines,
345 time stamps, and scheduling. It dynamically compiles entries into an
346 agenda that utilizes and smoothly integrates much of the Emacs calendar
347 and diary. Plain text URL-like links connect to websites, emails,
348 Usenet messages, BBDB entries, and any files related to the projects.
349 For printing and sharing of notes, an Org-mode file can be exported as a
350 structured ASCII file, as HTML, or (todo and agenda items only) as an
351 iCalendar file. It can also serve as a publishing tool for a set of
354 An important design aspect that distinguishes Org-mode from for
355 example Planner/Muse is that it encourages to store every piece of
356 information only once. In Planner, you have project pages, day pages
357 and possibly other files, duplicating some information such as tasks.
358 In Org-mode, you only have notes files. In your notes you mark entries
359 as tasks, label them with tags and timestamps. All necessary lists
360 like a schedule for the day, the agenda for a meeting, tasks lists
361 selected by tags etc are created dynamically when you need them.
363 Org-mode keeps simple things simple. When first fired up, it should
364 feel like a straightforward, easy to use outliner. Complexity is not
365 imposed, but a large amount of functionality is available when you need
366 it. Org-mode is a toolbox and can be used in different ways, for
369 * outline extension with visibility cycling and structure editing
370 * ASCII system and table editor for taking structured notes
371 * ASCII table editor with spreadsheet-like capabilities
373 * full agenda and planner with deadlines and work scheduling
374 * environment to implement David Allen's GTD system
375 * a basic database application
376 * simple hypertext system, with HTML export
377 * publishing tool to create a set of interlinked webpages
379 Org-mode's automatic, context sensitive table editor with spreadsheet
380 capabilities can be integrated into any major mode by activating the
381 minor Orgtbl-mode. Using a translation step, it can be used to maintain
382 tables in arbitrary file types, for example in LaTeX. The structure
383 editing and list creation capabilities can be used outside Org-mode with
384 the minor Orgstruct-mode.
386 There is a website for Org-mode which provides links to the newest
387 version of Org-mode, as well as additional information, frequently asked
388 questions (FAQ), links to tutorials etc. This page is located at
389 `http://www.astro.uva.nl/~dominik/Tools/org/'.
392 File: org, Node: Installation, Next: Activation, Prev: Summary, Up: Introduction
397 Important: If Org-mode is part of the Emacs distribution or an XEmacs
398 package, please skip this section and go directly to *Note Activation::.
400 If you have downloaded Org-mode from the Web, you must take the
401 following steps to install it: Go into the Org-mode distribution
402 directory and edit the top section of the file `Makefile'. You must
403 set the name of the Emacs binary (likely either `emacs' or `xemacs'),
404 and the paths to the directories where local Lisp and Info files are
405 kept. If you don't have access to the system-wide directories, create
406 your own two directories for these files, enter them into the Makefile,
407 and make sure Emacs finds the Lisp files by adding the following line
410 (setq load-path (cons "~/path/to/lispdir" load-path))
412 XEmacs users now need to install the file `noutline.el' from the
413 `xemacs' subdirectory of the Org-mode distribution. Use the command:
415 make install-noutline
417 Now byte-compile and install the Lisp files with the shell commands:
422 If you want to install the info documentation, use this command:
426 Then add to `.emacs':
428 ;; This line only if org-mode is not part of the X/Emacs distribution.
429 (require 'org-install)
432 File: org, Node: Activation, Next: Feedback, Prev: Installation, Up: Introduction
437 Add the following lines to your `.emacs' file. The last two lines
438 define _global_ keys for the commands `org-store-link' and `org-agenda'
439 - please choose suitable keys yourself.
441 ;; The following lines are always needed. Choose your own keys.
442 (add-to-list 'auto-mode-alist '("\\.org\\'" . org-mode))
443 (global-set-key "\C-cl" 'org-store-link)
444 (global-set-key "\C-ca" 'org-agenda)
446 Furthermore, you must activate `font-lock-mode' in org-mode buffers,
447 because significant functionality depends on font-locking being active.
448 You can do this with either one of the following two lines (XEmacs
449 user must use the second option):
450 (global-font-lock-mode 1) ; for all buffers
451 (add-hook 'org-mode-hook 'turn-on-font-lock) ; org-mode buffers only
453 With this setup, all files with extension `.org' will be put into
454 Org-mode. As an alternative, make the first line of a file look like
457 MY PROJECTS -*- mode: org; -*-
459 which will select Org-mode for this buffer no matter what the file's
460 name is. See also the variable `org-insert-mode-line-in-empty-file'.
463 File: org, Node: Feedback, Prev: Activation, Up: Introduction
468 If you find problems with Org-mode, or if you have questions, remarks,
469 or ideas about it, please contact the maintainer Carsten Dominik at
470 <dominik at science dot uva dot nl>.
472 For bug reports, please provide as much information as possible,
473 including the version information of Emacs (`C-h v emacs-version
474 <RET>') and Org-mode (`C-h v org-version <RET>'), as well as the
475 Org-mode related setup in `.emacs'. If an error occurs, a backtrace
476 can be very useful (see below on how to create one). Often a small
477 example file helps, along with clear information about:
479 1. What exactly did you do?
481 2. What did you expect to happen?
483 3. What happened instead?
484 Thank you for helping to improve this mode.
486 How to create a useful backtrace
487 ................................
489 If working with Org-mode produces an error with a message you don't
490 understand, you may have hit a bug. The best way to report this is by
491 providing, in addition to what was mentioned above, a _Backtrace_.
492 This is information from the built-in debugger about where and how the
493 error occurred. Here is how to produce a useful backtrace:
495 1. Start a fresh Emacs or XEmacs, and make sure that it will load the
496 original Lisp code in `org.el' instead of the compiled version in
497 `org.elc'. The backtrace contains much more information if it is
498 produced with uncompiled code. To do this, either rename `org.elc'
499 to something else before starting Emacs, or ask Emacs explicitly
500 to load `org.el' by using the command line
501 emacs -l /path/to/org.el
503 2. Go to the `Options' menu and select `Enter Debugger on Error'
504 (XEmacs has this option in the `Troubleshooting' sub-menu).
506 3. Do whatever you have to do to hit the error. Don't forget to
507 document the steps you take.
509 4. When you hit the error, a `*Backtrace*' buffer will appear on the
510 screen. Save this buffer to a file (for example using `C-x C-w')
511 and attach it to your bug report.
514 File: org, Node: Document structure, Next: Tables, Prev: Introduction, Up: Top
519 Org-mode is based on outline mode and provides flexible commands to
520 edit the structure of the document.
524 * Outlines:: Org-mode is based on outline-mode
525 * Headlines:: How to typeset org-tree headlines
526 * Visibility cycling:: Show and hide, much simplified
527 * Motion:: Jumping to other headlines
528 * Structure editing:: Changing sequence and level of headlines
529 * Archiving:: Move done task trees to a different place
530 * Sparse trees:: Matches embedded in context
531 * Plain lists:: Additional structure within an entry
532 * Drawers:: Tucking stuff away
533 * orgstruct-mode:: Structure editing outside Org-mode
536 File: org, Node: Outlines, Next: Headlines, Prev: Document structure, Up: Document structure
541 Org-mode is implemented on top of outline-mode. Outlines allow a
542 document to be organized in a hierarchical structure, which (at least
543 for me) is the best representation of notes and thoughts. An overview
544 of this structure is achieved by folding (hiding) large parts of the
545 document to show only the general document structure and the parts
546 currently being worked on. Org-mode greatly simplifies the use of
547 outlines by compressing the entire show/hide functionality into a single
548 command `org-cycle', which is bound to the <TAB> key.
551 File: org, Node: Headlines, Next: Visibility cycling, Prev: Outlines, Up: Document structure
556 Headlines define the structure of an outline tree. The headlines in
557 Org-mode start with one or more stars, on the left margin(1). For
567 * Another top level headline
569 Some people find the many stars too noisy and would prefer an outline
570 that has whitespace followed by a single star as headline starters.
571 *Note Clean view:: describes a setup to realize this.
573 An empty line after the end of a subtree is considered part of it and
574 will be hidden when the subtree is folded. However, if you leave at
575 least two empty lines, one empty line will remain visible after folding
576 the subtree, in order to structure the collapsed view. See the
577 variable `org-cycle-separator-lines' to modify this behavior.
579 ---------- Footnotes ----------
581 (1) See the variable `org-special-ctrl-a/e' to configure special
582 behavior of `C-a' and `C-e' in headlines.
585 File: org, Node: Visibility cycling, Next: Motion, Prev: Headlines, Up: Document structure
587 2.3 Visibility cycling
588 ======================
590 Outlines make it possible to hide parts of the text in the buffer.
591 Org-mode uses just two commands, bound to <TAB> and `S-<TAB>' to change
592 the visibility in the buffer.
595 _Subtree cycling_: Rotate current subtree among the states
597 ,-> FOLDED -> CHILDREN -> SUBTREE --.
598 '-----------------------------------'
600 The cursor must be on a headline for this to work(1). When the
601 cursor is at the beginning of the buffer and the first line is not
602 a headline, then <TAB> actually runs global cycling (see
603 below)(2). Also when called with a prefix argument (`C-u <TAB>'),
604 global cycling is invoked.
608 _Global cycling_: Rotate the entire buffer among the states
610 ,-> OVERVIEW -> CONTENTS -> SHOW ALL --.
611 '--------------------------------------'
613 When `S-<TAB>' is called with a numerical prefix N, the CONTENTS
614 view up to headlines of level N will be shown. Note that inside
615 tables, `S-<TAB>' jumps to the previous field.
621 Reveal context around point, showing the current entry, the
622 following heading and the hierarchy above. Useful for working
623 near a location exposed by a sparse tree command (*note Sparse
624 trees::) or an agenda command (*note Agenda commands::). With
625 prefix arg show, on each level, all sibling headings.
628 Show the current subtree in an indirect buffer(3). With numerical
629 prefix ARG, go up to this level and then take that tree. If ARG is
630 negative, go up that many levels. With `C-u' prefix, do not remove
631 the previously used indirect buffer.
633 When Emacs first visits an Org-mode file, the global state is set to
634 OVERVIEW, i.e. only the top level headlines are visible. This can be
635 configured through the variable `org-startup-folded', or on a per-file
636 basis by adding one of the following lines anywhere in the buffer:
642 ---------- Footnotes ----------
644 (1) see, however, the option `org-cycle-emulate-tab'.
646 (2) see the option `org-cycle-global-at-bob'.
648 (3) The indirect buffer (*note Indirect Buffers: (emacs)Indirect
649 Buffers.) will contain the entire buffer, but will be narrowed to the
650 current tree. Editing the indirect buffer will also change the
651 original buffer, but without affecting visibility in that buffer.
654 File: org, Node: Motion, Next: Structure editing, Prev: Visibility cycling, Up: Document structure
659 The following commands jump to other headlines in the buffer.
668 Next heading same level.
671 Previous heading same level.
674 Backward to higher level heading.
677 Jump to a different place without changing the current outline
678 visibility. Shows the document structure in a temporary buffer,
679 where you can use the following keys to find your destination:
680 <TAB> Cycle visibility.
681 <down> / <up> Next/previous visible headline.
682 n / p Next/previous visible headline.
683 f / b Next/previous headline same level.
686 <RET> Select this location.
689 File: org, Node: Structure editing, Next: Archiving, Prev: Motion, Up: Document structure
691 2.5 Structure editing
692 =====================
695 Insert new heading with same level as current. If the cursor is
696 in a plain list item, a new item is created (*note Plain lists::).
697 To force creation of a new headline, use a prefix arg, or first
698 press <RET> to get to the beginning of the next line. When this
699 command is used in the middle of a line, the line is split and the
700 rest of the line becomes the new headline. If the command is used
701 at the beginning of a headline, the new headline is created before
702 the current line. If at the beginning of any other line, the
703 content of that line is made the new heading. If the command is
704 used at the end of a folded subtree (i.e. behind the ellipses at
705 the end of a headline), then a headline like the current one will
706 be inserted after the end of the subtree.
709 Insert new TODO entry with same level as current heading.
712 Promote current heading by one level.
715 Demote current heading by one level.
718 Promote the current subtree by one level.
721 Demote the current subtree by one level.
724 Move subtree up (swap with previous subtree of same level).
727 Move subtree down (swap with next subtree of same level).
731 Kill subtree, i.e. remove it from buffer but save in kill ring.
734 Copy subtree to kill ring.
737 Yank subtree from kill ring. This does modify the level of the
738 subtree to make sure the tree fits in nicely at the yank position.
739 The yank level can also be specified with a prefix arg, or by
740 yanking after a headline marker like `****'.
743 Sort same-level entries. When there is an active region, all
744 entries in the region will be sorted. Otherwise the children of
745 the current headline are sorted. The command prompts for the
746 sorting method, which can be alphabetically, numerically, by time
747 (using the first time stamp in each entry), by priority, and each
748 of these in reverse order. With a `C-u' prefix, sorting will be
749 case-sensitive. With two `C-u C-u' prefixes, duplicate entries
750 will also be removed.
752 When there is an active region (transient-mark-mode), promotion and
753 demotion work on all headlines in the region. To select a region of
754 headlines, it is best to place both point and mark at the beginning of a
755 line, mark at the beginning of the first headline, and point at the line
756 just after the last headline to change. Note that when the cursor is
757 inside a table (*note Tables::), the Meta-Cursor keys have different
761 File: org, Node: Archiving, Next: Sparse trees, Prev: Structure editing, Up: Document structure
766 When a project represented by a (sub)tree is finished, you may want to
767 move the tree out of the way and to stop it from contributing to the
768 agenda. Org-mode knows two ways of archiving. You can mark a tree with
769 the ARCHIVE tag, or you can move an entire (sub)tree to a different
774 * ARCHIVE tag:: Marking a tree as inactive
775 * Moving subtrees:: Moving a tree to an archive file
778 File: org, Node: ARCHIVE tag, Next: Moving subtrees, Prev: Archiving, Up: Archiving
780 2.6.1 The ARCHIVE tag
781 ---------------------
783 A headline that is marked with the ARCHIVE tag (*note Tags::) stays at
784 its location in the outline tree, but behaves in the following way:
785 - It does not open when you attempt to do so with a visibility
786 cycling command (*note Visibility cycling::). You can force
787 cycling archived subtrees with `C-<TAB>', or by setting the option
788 `org-cycle-open-archived-trees'. Also normal outline commands like
789 `show-all' will open archived subtrees.
791 - During sparse tree construction (*note Sparse trees::), matches in
792 archived subtrees are not exposed, unless you configure the option
793 `org-sparse-tree-open-archived-trees'.
795 - During agenda view construction (*note Agenda views::), the
796 content of archived trees is ignored unless you configure the
797 option `org-agenda-skip-archived-trees'.
799 - Archived trees are not exported (*note Exporting::), only the
800 headline is. Configure the details using the variable
801 `org-export-with-archived-trees'.
803 The following commands help managing the ARCHIVE tag:
806 Toggle the ARCHIVE tag for the current headline. When the tag is
807 set, the headline changes to a shadowish face, and the subtree
811 Check if any direct children of the current headline should be
812 archived. To do this, each subtree is checked for open TODO
813 entries. If none are found, the command offers to set the ARCHIVE
814 tag for the child. If the cursor is _not_ on a headline when this
815 command is invoked, the level 1 trees will be checked.
818 Cycle a tree even if it is tagged with ARCHIVE.
821 File: org, Node: Moving subtrees, Prev: ARCHIVE tag, Up: Archiving
823 2.6.2 Moving subtrees
824 ---------------------
826 Once an entire project is finished, you may want to move it to a
827 different location, either in the current file, or even in a different
828 file, the archive file.
831 Archive the subtree starting at the cursor position to the location
832 given by `org-archive-location'. Context information that could be
833 lost like the file name, the category, inherited tags, and the todo
834 state will be store as properties in the entry.
837 Check if any direct children of the current headline could be
838 moved to the archive. To do this, each subtree is checked for
839 open TODO entries. If none are found, the command offers to move
840 it to the archive location. If the cursor is _not_ on a headline
841 when this command is invoked, the level 1 trees will be checked.
843 The default archive location is a file in the same directory as the
844 current file, with the name derived by appending `_archive' to the
845 current file name. For information and examples on how to change this,
846 see the documentation string of the variable `org-archive-location'.
847 There is also an in-buffer option for setting this variable, for example
851 You may have several such lines in the buffer, they will then be valid
852 for the entries following the line (the first will also apply to any
856 File: org, Node: Sparse trees, Next: Plain lists, Prev: Archiving, Up: Document structure
861 An important feature of Org-mode is the ability to construct _sparse
862 trees_ for selected information in an outline tree. A sparse tree
863 means that the entire document is folded as much as possible, but the
864 selected information is made visible along with the headline structure
865 above it(1). Just try it out and you will see immediately how it works.
867 Org-mode contains several commands creating such trees. The most
868 basic one is `org-occur':
871 Occur. Prompts for a regexp and shows a sparse tree with all
872 matches. If the match is in a headline, the headline is made
873 visible. If the match is in the body of an entry, headline and
874 body are made visible. In order to provide minimal context, also
875 the full hierarchy of headlines above the match is shown, as well
876 as the headline following the match. Each match is also
877 highlighted; the highlights disappear when the buffer is changed
878 by an editing command, or by pressing `C-c C-c'. When called with
879 a `C-u' prefix argument, previous highlights are kept, so several
880 calls to this command can be stacked.
881 For frequently used sparse trees of specific search strings, you can
882 use the variable `org-agenda-custom-commands' to define fast keyboard
883 access to specific sparse trees. These commands will then be
884 accessible through the agenda dispatcher (*note Agenda dispatcher::).
887 (setq org-agenda-custom-commands
888 '(("f" occur-tree "FIXME")))
890 will define the key `C-c a f' as a shortcut for creating a sparse tree
891 matching the string `FIXME'.
893 Other commands use sparse trees as well. For example `C-c C-v'
894 creates a sparse TODO tree (*note TODO basics::).
896 To print a sparse tree, you can use the Emacs command
897 `ps-print-buffer-with-faces' which does not print invisible parts of
898 the document (2). Or you can use the command `C-c C-e v' to export
899 only the visible part of the document and print the resulting file.
901 ---------- Footnotes ----------
903 (1) See also the variables `org-show-hierarchy-above',
904 `org-show-following-heading', and `org-show-siblings' for detailed
905 control on how much context is shown around each match.
907 (2) This does not work under XEmacs, because XEmacs uses selective
908 display for outlining, not text properties.
911 File: org, Node: Plain lists, Next: Drawers, Prev: Sparse trees, Up: Document structure
916 Within an entry of the outline tree, hand-formatted lists can provide
917 additional structure. They also provide a way to create lists of
918 checkboxes (*note Checkboxes::). Org-mode supports editing such lists,
919 and the HTML exporter (*note Exporting::) does parse and format them.
921 Org-mode knows ordered and unordered lists. Unordered list items
922 start with `-', `+', or `*'(1) as bullets. Ordered list items start
923 with `1.' or `1)'. Items belonging to the same list must have the same
924 indentation on the first line. In particular, if an ordered list
925 reaches number `10.', then the 2-digit numbers must be written
926 left-aligned with the other numbers in the list. Indentation also
927 determines the end of a list item. It ends before the next line that
928 is indented like the bullet/number, or less. Empty lines are part of
929 the previous item, so you can have several paragraphs in one item. If
930 you would like an empty line to terminate all currently open plain
931 lists, configure the variable `org-empty-line-terminates-plain-lists'.
935 My favorite scenes are (in this order)
936 1. The attack of the Rohirrim
937 2. Eowyns fight with the witch king
938 + this was already my favorite scene in the book
939 + I really like Miranda Otto.
940 3. Peter Jackson being shot by Legolas
942 He makes a really funny face when it happens.
943 But in the end, not individual scenes matter but the film as a whole.
945 Org-mode supports these lists by tuning filling and wrapping
946 commands to deal with them correctly(2).
948 The following commands act on items when the cursor is in the first
949 line of an item (the line with the bullet or number).
952 Items can be folded just like headline levels if you set the
953 variable `org-cycle-include-plain-lists'. The level of an item is
954 then given by the indentation of the bullet/number. Items are
955 always subordinate to real headlines, however; the hierarchies
956 remain completely separated.
958 If `org-cycle-include-plain-lists' has not been set, <TAB> fixes
959 the indentation of the curent line in a heuristic way.
962 Insert new item at current level. With prefix arg, force a new
963 heading (*note Structure editing::). If this command is used in
964 the middle of a line, the line is _split_ and the rest of the line
965 becomes the new item. If this command is executed in the
966 _whitespace before a bullet or number_, the new item is created
967 _before_ the current item. If the command is executed in the
968 white space before the text that is part of an item but does not
969 contain the bullet, a bullet is added to the current line.
972 Insert a new item with a checkbox (*note Checkboxes::).
976 Jump to the previous/next item in the current list.
980 Move the item including subitems up/down (swap with previous/next
981 item of same indentation). If the list is ordered, renumbering is
986 Decrease/increase the indentation of the item, including subitems.
987 Initially, the item tree is selected based on current indentation.
988 When these commands are executed several times in direct
989 succession, the initially selected region is used, even if the new
990 indentation would imply a different hierarchy. To use the new
991 hierarchy, break the command chain with a cursor motion or so.
994 If there is a checkbox (*note Checkboxes::) in the item line,
995 toggle the state of the checkbox. If not, make this command makes
996 sure that all the items on this list level use the same bullet.
997 Furthermore, if this is an ordered list, make sure the numbering
1001 Cycle the entire list level through the different itemize/enumerate
1002 bullets (`-', `+', `*', `1.', `1)'). With prefix arg, select the
1003 nth bullet from this list.
1005 ---------- Footnotes ----------
1007 (1) When using `*' as a bullet, lines must be indented or they will
1008 be seen as top-level headlines. Also, when you are hiding leading
1009 stars to get a clean outline view, plain list items starting with a
1010 star are visually indistinguishable from true headlines. In short:
1011 even though `*' is supported, it may be better not to use it for plain
1014 (2) Org-mode only changes the filling settings for Emacs. For
1015 XEmacs, you should use Kyle E. Jones' `filladapt.el'. To turn this on,
1016 put into `.emacs': `(require 'filladapt)'
1019 File: org, Node: Drawers, Next: orgstruct-mode, Prev: Plain lists, Up: Document structure
1024 Sometimes you want to keep information associated with an entry, but you
1025 normally don't want to see it. For this, Org-mode has _drawers_.
1026 Drawers need to be configured with the variable `org-drawers', and look
1029 ** This is a headline
1030 Still outside the drawer
1032 This is inside the drawer.
1036 Visibility cycling (*note Visibility cycling::) on the headline will
1037 hide and show the entry, but keep the drawer collapsed to a single line.
1038 In order to look inside the drawer, you need to move the cursor to the
1039 drawer line and press <TAB> there. Org-mode uses a drawer for storing
1040 properties (*note Properties and columns::).
1043 File: org, Node: orgstruct-mode, Prev: Drawers, Up: Document structure
1045 2.10 The Orgstruct minor mode
1046 =============================
1048 If you like the intuitive way the Org-mode structure editing and list
1049 formatting works, you might want to use these commands in other modes
1050 like text-mode or mail-mode as well. The minor mode Orgstruct-mode
1051 makes this possible. You can always toggle the mode with `M-x
1052 orgstruct-mode'. To turn it on by default, for example in mail mode,
1055 (add-hook 'mail-mode-hook 'turn-on-orgstruct)
1057 When this mode is active and the cursor is on a line that looks to
1058 Org-mode like a headline of the first line of a list item, most
1059 structure editing commands will work, even if the same keys normally
1060 have different functionality in the major mode you are using. If the
1061 cursor is not in one of those special lines, Orgstruct-mode lurks
1062 silently in the shadow.
1065 File: org, Node: Tables, Next: Hyperlinks, Prev: Document structure, Up: Top
1070 Org-mode has a very fast and intuitive table editor built-in.
1071 Spreadsheet-like calculations are supported in connection with the
1072 Emacs `calc' package.
1076 * Built-in table editor:: Simple tables
1077 * Narrow columns:: Stop wasting space in tables
1078 * Column groups:: Grouping to trigger vertical lines
1079 * orgtbl-mode:: The table editor as minor mode
1080 * The spreadsheet:: The table editor has spreadsheet capabilities.
1083 File: org, Node: Built-in table editor, Next: Narrow columns, Prev: Tables, Up: Tables
1085 3.1 The built-in table editor
1086 =============================
1088 Org-mode makes it easy to format tables in plain ASCII. Any line with
1089 `|' as the first non-whitespace character is considered part of a
1090 table. `|' is also the column separator. A table might look like this:
1092 | Name | Phone | Age |
1093 |-------+-------+-----|
1094 | Peter | 1234 | 17 |
1095 | Anna | 4321 | 25 |
1097 A table is re-aligned automatically each time you press <TAB> or
1098 <RET> or `C-c C-c' inside the table. <TAB> also moves to the next
1099 field (<RET> to the next row) and creates new table rows at the end of
1100 the table or before horizontal lines. The indentation of the table is
1101 set by the first line. Any line starting with `|-' is considered as a
1102 horizontal separator line and will be expanded on the next re-align to
1103 span the whole table width. So, to create the above table, you would
1109 and then press <TAB> to align the table and start filling in fields.
1111 When typing text into a field, Org-mode treats <DEL>, <Backspace>,
1112 and all character keys in a special way, so that inserting and deleting
1113 avoids shifting other fields. Also, when typing _immediately after the
1114 cursor was moved into a new field with `<TAB>', `S-<TAB>' or `<RET>'_,
1115 the field is automatically made blank. If this behavior is too
1116 unpredictable for you, configure the variables
1117 `org-enable-table-editor' and `org-table-auto-blank-field'.
1119 Creation and conversion
1120 .......................
1123 Convert the active region to table. If every line contains at
1124 least one TAB character, the function assumes that the material is
1125 tab separated. If not, lines are split at whitespace into fields.
1126 You can use a prefix argument to indicate the minimum number of
1127 consecutive spaces required to identify a field separator
1128 (default: just one).
1129 If there is no active region, this command creates an empty
1130 Org-mode table. But it's easier just to start typing, like
1131 `|Name|Phone|Age <RET> |- <TAB>'.
1133 Re-aligning and field motion
1134 ............................
1137 Re-align the table without moving the cursor.
1140 Re-align the table, move to the next field. Creates a new row if
1144 Re-align, move to previous field.
1147 Re-align the table and move down to next row. Creates a new row if
1148 necessary. At the beginning or end of a line, <RET> still does
1149 NEWLINE, so it can be used to split a table.
1151 Column and row editing
1152 ......................
1156 Move the current column left/right.
1159 Kill the current column.
1162 Insert a new column to the left of the cursor position.
1166 Move the current row up/down.
1169 Kill the current row or horizontal line.
1172 Insert a new row above (with arg: below) the current row.
1175 Insert a horizontal line below current row. With prefix arg, the
1176 line is created above the current line.
1179 Sort the table lines in the region. The position of point
1180 indicates the column to be used for sorting, and the range of
1181 lines is the range between the nearest horizontal separator lines,
1182 or the entire table. If point is before the first column, you
1183 will be prompted for the sorting column. If there is an active
1184 region, the mark specifies the first line and the sorting column,
1185 while point should be in the last line to be included into the
1186 sorting. The command prompts for the sorting type
1187 (alphabetically, numerically, or by time). When called with a
1188 prefix argument, alphabetic sorting will be case-sensitive.
1194 Copy a rectangular region from a table to a special clipboard.
1195 Point and mark determine edge fields of the rectangle. The
1196 process ignores horizontal separator lines.
1199 Copy a rectangular region from a table to a special clipboard, and
1200 blank all fields in the rectangle. So this is the "cut" operation.
1203 Paste a rectangular region into a table. The upper right corner
1204 ends up in the current field. All involved fields will be
1205 overwritten. If the rectangle does not fit into the present table,
1206 the table is enlarged as needed. The process ignores horizontal
1210 Wrap several fields in a column like a paragraph. If there is an
1211 active region, and both point and mark are in the same column, the
1212 text in the column is wrapped to minimum width for the given
1213 number of lines. A prefix ARG may be used to change the number of
1214 desired lines. If there is no region, the current field is split
1215 at the cursor position and the text fragment to the right of the
1216 cursor is prepended to the field one line down. If there is no
1217 region, but you specify a prefix ARG, the current field is made
1218 blank, and the content is appended to the field above.
1224 Sum the numbers in the current column, or in the rectangle defined
1225 by the active region. The result is shown in the echo area and can
1226 be inserted with `C-y'.
1229 When current field is empty, copy from first non-empty field above.
1230 When not empty, copy current field down to next row and move cursor
1231 along with it. Depending on the variable
1232 `org-table-copy-increment', integer field values will be
1233 incremented during copy. This key is also used by CUA-mode (*note
1240 Edit the current field in a separate window. This is useful for
1241 fields that are not fully visible (*note Narrow columns::). When
1242 called with a `C-u' prefix, just make the full field visible, so
1243 that it can be edited in place.
1246 This is an alias for `C-u C-c `' to make the current field fully
1249 `M-x org-table-import'
1250 Import a file as a table. The table should be TAB- or whitespace
1251 separated. Useful, for example, to import an Excel table or data
1252 from a database, because these programs generally can write
1253 TAB-separated text files. This command works by inserting the
1254 file into the buffer and then converting the region to a table.
1255 Any prefix argument is passed on to the converter, which uses it
1256 to determine the separator.
1259 Tables can also be imported by pasting tabular text into the
1260 org-mode buffer, selecting the pasted text with `C-x C-x' and then
1261 using the `C-c |' command (see above under Creation and conversion.
1263 `M-x org-table-export'
1264 Export the table as a TAB-separated file. Useful for data
1265 exchange with, for example, Excel or database programs.
1267 If you don't like the automatic table editor because it gets in your
1268 way on lines which you would like to start with `|', you can turn it
1271 (setq org-enable-table-editor nil)
1273 Then the only table command that still works is `C-c C-c' to do a
1277 File: org, Node: Narrow columns, Next: Column groups, Prev: Built-in table editor, Up: Tables
1282 The width of columns is automatically determined by the table editor.
1283 Sometimes a single field or a few fields need to carry more text,
1284 leading to inconveniently wide columns. To limit(1) the width of a
1285 column, one field anywhere in the column may contain just the string
1286 `<N>' where `N' is an integer specifying the width of the column in
1287 characters. The next re-align will then set the width of this column
1288 to no more than this value.
1290 |---+------------------------------| |---+--------|
1292 | 1 | one | | 1 | one |
1293 | 2 | two | ----\ | 2 | two |
1294 | 3 | This is a long chunk of text | ----/ | 3 | This=> |
1295 | 4 | four | | 4 | four |
1296 |---+------------------------------| |---+--------|
1298 Fields that are wider become clipped and end in the string `=>'. Note
1299 that the full text is still in the buffer, it is only invisible. To
1300 see the full text, hold the mouse over the field - a tool-tip window
1301 will show the full content. To edit such a field, use the command `C-c
1302 `' (that is `C-c' followed by the backquote). This will open a new
1303 window with the full field. Edit it and finish with `C-c C-c'.
1305 When visiting a file containing a table with narrowed columns, the
1306 necessary character hiding has not yet happened, and the table needs to
1307 be aligned before it looks nice. Setting the option
1308 `org-startup-align-all-tables' will realign all tables in a file upon
1309 visiting, but also slow down startup. You can also set this option on
1310 a per-file basis with:
1315 ---------- Footnotes ----------
1317 (1) This feature does not work on XEmacs.
1320 File: org, Node: Column groups, Next: orgtbl-mode, Prev: Narrow columns, Up: Tables
1325 When Org-mode exports tables, it does so by default without vertical
1326 lines because that is visually more satisfying in general. Occasionally
1327 however, vertical lines can be useful to structure a table into groups
1328 of columns, much like horizontal lines can do for groups of rows. In
1329 order to specify column groups, you can use a special row where the
1330 first field contains only `/'. The further fields can either contain
1331 `<' to indicate that this column should start a group, `>' to indicate
1332 the end of a column, or `<>' to make a column a group of its own.
1333 Boundaries between colum groups will upon export be marked with
1334 vertical lines. Here is an example:
1336 | | N | N^2 | N^3 | N^4 | sqrt(n) | sqrt[4](N) |
1337 |---+----+-----+-----+-----+---------+------------|
1338 | / | <> | < | | > | < | > |
1339 | # | 1 | 1 | 1 | 1 | 1 | 1 |
1340 | # | 2 | 4 | 8 | 16 | 1.4142 | 1.1892 |
1341 | # | 3 | 9 | 27 | 81 | 1.7321 | 1.3161 |
1342 |---+----+-----+-----+-----+---------+------------|
1343 #+TBLFM: $3=$2^2::$4=$2^3::$5=$2^4::$6=sqrt($2)::$7=sqrt(sqrt(($2))
1345 It is also sufficient to just insert the colum group starters after
1346 every vertical line you'd like to have:
1348 | N | N^2 | N^3 | N^4 | sqrt(n) | sqrt[4](N) |
1349 |----+-----+-----+-----+---------+------------|
1353 File: org, Node: orgtbl-mode, Next: The spreadsheet, Prev: Column groups, Up: Tables
1355 3.4 The Orgtbl minor mode
1356 =========================
1358 If you like the intuitive way the Org-mode table editor works, you
1359 might also want to use it in other modes like text-mode or mail-mode.
1360 The minor mode Orgtbl-mode makes this possible. You can always toggle
1361 the mode with `M-x orgtbl-mode'. To turn it on by default, for example
1364 (add-hook 'mail-mode-hook 'turn-on-orgtbl)
1366 Furthermore, with some special setup, it is possible to maintain
1367 tables in arbitrary syntax with Orgtbl-mode. For example, it is
1368 possible to construct LaTeX tables with the underlying ease and power of
1369 Orgtbl-mode, including spreadsheet capabilities. For details, see
1370 *Note Tables in arbitrary syntax::.
1373 File: org, Node: The spreadsheet, Prev: orgtbl-mode, Up: Tables
1378 The table editor makes use of the Emacs `calc' package to implement
1379 spreadsheet-like capabilities. It can also evaluate Emacs Lisp forms to
1380 derive fields from other fields. While fully featured, Org-mode's
1381 implementation is not identical to other spreadsheets. For example,
1382 Org-mode knows the concept of a _column formula_ that will be applied
1383 to all non-header fields in a column without having to copy the formula
1384 to each relevant field.
1388 * References:: How to refer to another field or range
1389 * Formula syntax for Calc:: Using Calc to compute stuff
1390 * Formula syntax for Lisp:: Writing formulas in Emacs Lisp
1391 * Field formulas:: Formulas valid for a single field
1392 * Column formulas:: Formulas valid for an entire column
1393 * Editing and debugging formulas:: Fixing formulas
1394 * Updating the table:: Recomputing all dependent fields
1395 * Advanced features:: Field names, parameters and automatic recalc
1398 File: org, Node: References, Next: Formula syntax for Calc, Prev: The spreadsheet, Up: The spreadsheet
1403 To compute fields in the table from other fields, formulas must
1404 reference other fields or ranges. In Org-mode, fields can be referenced
1405 by name, by absolute coordinates, and by relative coordinates. To find
1406 out what the coordinates of a field are, press `C-c ?' in that field,
1407 or press `C-c }' to toggle the display of a grid.
1412 Formulas can reference the value of another field in two ways. Like in
1413 any other spreadsheet, you may reference fields with a letter/number
1414 combination like `B3', meaning the 2nd field in the 3rd row.
1416 Org-mode also uses another, more general operator that looks like this:
1419 Column references can be absolute like `1', `2',...`N', or relative to
1420 the current column like `+1' or `-2'.
1422 The row specification only counts data lines and ignores horizontal
1423 separator lines (hlines). You can use absolute row numbers `1'...`N',
1424 and row numbers relative to the current row like `+3' or `-1'. Or
1425 specify the row relative to one of the hlines: `I' refers to the first
1426 hline, `II' to the second etc. `-I' refers to the first such line
1427 above the current line, `+I' to the first such line below the current
1428 line. You can also write `III+2' which is the second data line after
1429 the third hline in the table. Relative row numbers like `-3' will not
1430 cross hlines if the current line is too close to the hline. Instead,
1431 the value directly at the hline is used.
1433 `0' refers to the current row and column. Also, if you omit either
1434 the column or the row part of the reference, the current row/column is
1437 Org-mode's references with _unsigned_ numbers are fixed references
1438 in the sense that if you use the same reference in the formula for two
1439 different fields, the same field will be referenced each time.
1440 Org-mode's references with _signed_ numbers are floating references
1441 because the same reference operator can reference different fields
1442 depending on the field being calculated by the formula.
1444 Here are a few examples:
1446 @2$3 2nd row, 3rd column
1448 $5 column 5 in the current row
1450 @2 current column, row 2
1451 @-1$-3 the field one row up, three columns to the left
1452 @-I$2 field just under hline above current row, column 2
1457 You may reference a rectangular range of fields by specifying two field
1458 references connected by two dots `..'. If both fields are in the
1459 current row, you may simply use `$2..$7', but if at least one field is
1460 in a different row, you need to use the general `@row$column' format at
1461 least for the first field (i.e the reference must start with `@' in
1462 order to be interpreted correctly). Examples:
1464 $1..$3 First three fields in the current row.
1465 $P..$Q Range, using column names (see under Advanced)
1466 @2$1..@4$3 6 fields between these two fields.
1467 A2..C4 Same as above.
1468 @-1$-2..@-1 3 numbers from the column to the left, 2 up to current row
1470 Range references return a vector of values that can be fed into Calc
1471 vector functions. Empty fields in ranges are normally suppressed, so
1472 that the vector contains only the non-empty fields (but see the `E'
1473 mode switch below). If there are no non-empty fields, `[0]' is
1474 returned to avoid syntax errors in formulas.
1479 `$name' is interpreted as the name of a column, parameter or constant.
1480 Constants are defined globally through the variable
1481 `org-table-formula-constants', and locally (for the file) through a
1484 #+CONSTANTS: c=299792458. pi=3.14 eps=2.4e-6
1486 Also properties (*note Properties and columns::) can be used as
1487 constants in table formulas: For a property `:XYZ:' use the name
1488 `$PROP_XYZ', and the property will be searched in the current outline
1489 entry and in the hierarchy above it. If you have the `constants.el'
1490 package, it will also be used to resolve constants, including natural
1491 constants like `$h' for Planck's constant, and units like `$km' for
1492 kilometers(1). Column names and parameters can be specified in special
1493 table lines. These are described below, see *Note Advanced features::.
1494 All names must start with a letter, and further consist of letters and
1497 ---------- Footnotes ----------
1499 (1) `Constant.el' can supply the values of constants in two
1500 different unit systems, `SI' and `cgs'. Which one is used depends on
1501 the value of the variable `constants-unit-system'. You can use the
1502 `#+STARTUP' options `constSI' and `constcgs' to set this value for the
1506 File: org, Node: Formula syntax for Calc, Next: Formula syntax for Lisp, Prev: References, Up: The spreadsheet
1508 3.5.2 Formula syntax for Calc
1509 -----------------------------
1511 A formula can be any algebraic expression understood by the Emacs
1512 `Calc' package. Note that `calc' has the non-standard convention that
1513 `/' has lower precedence than `*', so that `a/b*c' is interpreted as
1514 `a/(b*c)'. Before evaluation by `calc-eval' (*note calc-eval:
1515 (calc)Calling Calc from Your Programs.), variable substitution takes
1516 place according to the rules described above. The range vectors can be
1517 directly fed into the calc vector functions like `vmean' and `vsum'.
1519 A formula can contain an optional mode string after a semicolon.
1520 This string consists of flags to influence Calc and other modes during
1521 execution. By default, Org-mode uses the standard calc modes (precision
1522 12, angular units degrees, fraction and symbolic modes off. The display
1523 format, however, has been changed to `(float 5)' to keep tables
1524 compact. The default settings can be configured using the variable
1525 `org-calc-default-modes'.
1527 p20 switch the internal precision to 20 digits
1528 n3 s3 e2 f4 normal, scientific, engineering, or fixed display format
1529 D R angle modes: degrees, radians
1530 F S fraction and symbolic modes
1531 N interpret all fields as numbers, use 0 for non-numbers
1532 T force text interpretation
1533 E keep empty fields in ranges
1535 In addition, you may provide a `printf' format specifier to reformat
1536 the final result. A few examples:
1538 $1+$2 Sum of first and second field
1539 $1+$2;%.2f Same, format result to two decimals
1540 exp($2)+exp($1) Math functions can be used
1541 $0;%.1f Reformat current cell to 1 decimal
1542 ($3-32)*5/9 Degrees F -> C conversion
1543 $c/$1/$cm Hz -> cm conversion, using `constants.el'
1544 tan($1);Dp3s1 Compute in degrees, precision 3, display SCI 1
1545 sin($1);Dp3%.1e Same, but use printf specifier for display
1546 vmean($2..$7) Compute column range mean, using vector function
1547 vmean($2..$7);EN Same, but treat empty fields as 0
1548 taylor($3,x=7,2) taylor series of $3, at x=7, second degree
1550 Calc also contains a complete set of logical operations. For example
1552 if($1<20,teen,string("")) "teen" if age $1 less than 20, else empty
1555 File: org, Node: Formula syntax for Lisp, Next: Field formulas, Prev: Formula syntax for Calc, Up: The spreadsheet
1557 3.5.3 Emacs Lisp forms as formulas
1558 ----------------------------------
1560 It is also possible to write a formula in Emacs Lisp; this can be useful
1561 for string manipulation and control structures, if the Calc's
1562 functionality is not enough. If a formula starts with a single quote
1563 followed by an opening parenthesis, then it is evaluated as a lisp form.
1564 The evaluation should return either a string or a number. Just as with
1565 `calc' formulas, you can specify modes and a printf format after a
1566 semicolon. With Emacs Lisp forms, you need to be concious about the way
1567 field references are interpolated into the form. By default, a
1568 reference will be interpolated as a Lisp string (in double quotes)
1569 containing the field. If you provide the `N' mode switch, all
1570 referenced elements will be numbers (non-number fields will be zero) and
1571 interpolated as Lisp numbers, without quotes. If you provide the `L'
1572 flag, all fields will be interpolated literally, without quotes. I.e.,
1573 if you want a reference to be interpreted as a string by the Lisp form,
1574 enclode the reference operator itself in double quotes, like `"$3"'.
1575 Ranges are inserted as space-separated fields, so you can embed them in
1576 list or vector syntax. A few examples, note how the `N' mode is used
1577 when we do computations in lisp.
1579 Swap the first two characters of the content of column 1
1580 '(concat (substring $1 1 2) (substring $1 0 1) (substring $1 2))
1581 Add columns 1 and 2, equivalent to the Calc's `$1+$2'
1583 Compute the sum of columns 1-4, like Calc's `vsum($1..$4)'
1584 '(apply '+ '($1..$4));N
1587 File: org, Node: Field formulas, Next: Column formulas, Prev: Formula syntax for Lisp, Up: The spreadsheet
1589 3.5.4 Field formulas
1590 --------------------
1592 To assign a formula to a particular field, type it directly into the
1593 field, preceded by `:=', for example `:=$1+$2'. When you press <TAB>
1594 or <RET> or `C-c C-c' with the cursor still in the field, the formula
1595 will be stored as the formula for this field, evaluated, and the
1596 current field replaced with the result.
1598 Formulas are stored in a special line starting with `#+TBLFM:'
1599 directly below the table. If you typed the equation in the 4th field of
1600 the 3rd data line in the table, the formula will look like
1601 `@3$4=$1+$2'. When inserting/deleting/swapping column and rows with
1602 the appropriate commands, absolute references (but not relative ones)
1603 in stored formulas are modified in order to still reference the same
1604 field. Of cause this is not true if you edit the table structure with
1605 normal editing commands - then you must fix the equations yourself.
1607 Instead of typing an equation into the field, you may also use the
1611 Install a new formula for the current field. The command prompts
1612 for a formula, with default taken from the `#+TBLFM:' line, applies
1613 it to the current field and stores it.
1616 File: org, Node: Column formulas, Next: Editing and debugging formulas, Prev: Field formulas, Up: The spreadsheet
1618 3.5.5 Column formulas
1619 ---------------------
1621 Often in a table, the same formula should be used for all fields in a
1622 particular column. Instead of having to copy the formula to all fields
1623 in that column, org-mode allows to assign a single formula to an entire
1624 column. If the table contains horizontal separator hlines, everything
1625 before the first such line is considered part of the table _header_ and
1626 will not be modified by column formulas.
1628 To assign a formula to a column, type it directly into any field in
1629 the column, preceded by an equal sign, like `=$1+$2'. When you press
1630 <TAB> or <RET> or `C-c C-c' with the cursor still in the field, the
1631 formula will be stored as the formula for the current column, evaluated
1632 and the current field replaced with the result. If the field contains
1633 only `=', the previously stored formula for this column is used. For
1634 each column, Org-mode will only remember the most recently used
1635 formula. In the `TBLFM:' line, column formulas will look like
1638 Instead of typing an equation into the field, you may also use the
1642 Install a new formula for the current column and replace current
1643 field with the result of the formula. The command prompts for a
1644 formula, with default taken from the `#+TBLFM' line, applies it to
1645 the current field and stores it. With a numerical prefix (e.g.
1646 `C-5 C-c =') will apply it to that many consecutive fields in the
1650 File: org, Node: Editing and debugging formulas, Next: Updating the table, Prev: Column formulas, Up: The spreadsheet
1652 3.5.6 Editing and Debugging formulas
1653 ------------------------------------
1655 You can edit individual formulas in the minibuffer or directly in the
1656 field. Org-mode can also prepare a special buffer with all active
1657 formulas of a table. When offering a formula for editing, Org-mode
1658 converts references to the standard format (like `B3' or `D&') if
1659 possible. If you prefer to only work with the internal format (like
1660 `@3$2' or `$4'), configure the variable
1661 `org-table-use-standard-references'.
1665 Edit the formula associated with the current column/field in the
1666 minibuffer. See *Note Column formulas:: and *Note Field
1670 Re-insert the active formula (either a field formula, or a column
1671 formula) into the current field, so that you can edit it directly
1672 in the field. The advantage over editing in the minibuffer is
1673 that you can use the command `C-c ?'.
1676 While editing a formula in a table field, highlight the field(s)
1677 referenced by the reference at the cursor position in the formula.
1680 Toggle the display of row and column numbers for a table, using
1681 overlays. These are updated each time the table is aligned, you
1682 can force it with `C-c C-c'.
1685 Toggle the formula debugger on and off. See below.
1688 Edit all formulas for the current table in a special buffer, where
1689 the formulas will be displayed one per line. If the current field
1690 has an active formula, the cursor in the formula editor will mark
1691 it. While inside the special buffer, Org-mode will automatically
1692 highlight any field or range reference at the cursor position.
1693 You may edit, remove and add formulas, and use the following
1697 Exit the formula editor and store the modified formulas.
1698 With `C-u' prefix, also apply the new formulas to the entire
1702 Exit the formula editor without installing changes.
1705 Toggle all references in the formula editor between standard
1706 (like `B3') and internal (like `@3$2').
1709 Pretty-print or indent lisp formula at point. When in a line
1710 containing a lisp formula, format the formula according to
1711 Emacs Lisp rules. Another <TAB> collapses the formula back
1712 again. In the open formula, <TAB> re-indents just like in
1716 Complete Lisp symbols, just like in Emacs-lisp-mode.
1718 `S-<up>/<down>/<left>/<right>'
1719 Shift the reference at point. For example, if the reference
1720 is `B3' and you press `S-<right>', it will become `C3'. This
1721 also works for relative references, and for hline references.
1724 Move the test line for column formulas in the Org-mode buffer
1728 Scroll the window displaying the table.
1731 Turn the coordinate grid in the table on and off.
1733 Making a table field blank does not remove the formula associated
1734 with the field, because that is stored in a different line (the `TBLFM'
1735 line) - during the next recalculation the field will be filled again.
1736 To remove a formula from a field, you have to give an empty reply when
1737 prompted for the formula, or to edit the `#+TBLFM' line.
1739 You may edit the `#+TBLFM' directly and re-apply the changed
1740 equations with `C-c C-c' in that line, or with the normal recalculation
1741 commands in the table.
1746 When the evaluation of a formula leads to an error, the field content
1747 becomes the string `#ERROR'. If you would like see what is going on
1748 during variable substitution and calculation in order to find a bug,
1749 turn on formula debugging in the `Tbl' menu and repeat the calculation,
1750 for example by pressing `C-u C-u C-c = <RET>' in a field. Detailed
1751 information will be displayed.
1754 File: org, Node: Updating the table, Next: Advanced features, Prev: Editing and debugging formulas, Up: The spreadsheet
1756 3.5.7 Updating the Table
1757 ------------------------
1759 Recalculation of a table is normally not automatic, but needs to be
1760 triggered by a command. See *Note Advanced features:: for a way to make
1761 recalculation at least semi-automatically.
1763 In order to recalculate a line of a table or the entire table, use
1764 the following commands:
1767 Recalculate the current row by first applying the stored column
1768 formulas from left to right, and all field formulas in the current
1773 Recompute the entire table, line by line. Any lines before the
1774 first hline are left alone, assuming that these are part of the
1779 Iterate the table by recomputing it until no further changes occur.
1780 This may be necessary if some computed fields use the value of
1781 other fields that are computed later in the calculation sequence.
1784 File: org, Node: Advanced features, Prev: Updating the table, Up: The spreadsheet
1786 3.5.8 Advanced features
1787 -----------------------
1789 If you want the recalculation of fields to happen automatically, or if
1790 you want to be able to assign names to fields and columns, you need to
1791 reserve the first column of the table for special marking characters.
1793 Rotate the calculation mark in first column through the states `',
1794 `#', `*', `!', `$'. The meaning of these characters is discussed
1795 below. When there is an active region, change all marks in the
1798 Here is an example of a table that collects exam results of students
1799 and makes use of these features:
1801 |---+---------+--------+--------+--------+-------+------|
1802 | | Student | Prob 1 | Prob 2 | Prob 3 | Total | Note |
1803 |---+---------+--------+--------+--------+-------+------|
1804 | ! | | P1 | P2 | P3 | Tot | |
1805 | # | Maximum | 10 | 15 | 25 | 50 | 10.0 |
1806 | ^ | | m1 | m2 | m3 | mt | |
1807 |---+---------+--------+--------+--------+-------+------|
1808 | # | Peter | 10 | 8 | 23 | 41 | 8.2 |
1809 | # | Sara | 6 | 14 | 19 | 39 | 7.8 |
1810 | # | Sam | 2 | 4 | 3 | 9 | 1.8 |
1811 |---+---------+--------+--------+--------+-------+------|
1812 | | Average | | | | 29.7 | |
1813 | ^ | | | | | at | |
1814 | $ | max=50 | | | | | |
1815 |---+---------+--------+--------+--------+-------+------|
1816 #+TBLFM: $6=vsum($P1..$P3)::$7=10*$Tot/$max;%.1f::$at=vmean(@-II..@-I);%.1f
1818 Important: Please note that for these special tables, recalculating the
1819 table with `C-u C-c *' will only affect rows that are marked `#' or
1820 `*', and fields that have a formula assigned to the field itself. The
1821 column formulas are not applied in rows with empty first field.
1823 The marking characters have the following meaning:
1825 The fields in this line define names for the columns, so that you
1826 may refer to a column as `$Tot' instead of `$6'.
1829 This row defines names for the fields _above_ the row. With such
1830 a definition, any formula in the table may use `$m1' to refer to
1831 the value `10'. Also, if you assign a formula to a names field, it
1832 will be stored as `$name=...'.
1835 Similar to `^', but defines names for the fields in the row
1839 Fields in this row can define _parameters_ for formulas. For
1840 example, if a field in a `$' row contains `max=50', then formulas
1841 in this table can refer to the value 50 using `$max'. Parameters
1842 work exactly like constants, only that they can be defined on a
1846 Fields in this row are automatically recalculated when pressing
1847 <TAB> or <RET> or `S-<TAB>' in this row. Also, this row is
1848 selected for a global recalculation with `C-u C-c *'. Unmarked
1849 lines will be left alone by this command.
1852 Selects this line for global recalculation with `C-u C-c *', but
1853 not for automatic recalculation. Use this when automatic
1854 recalculation slows down editing too much.
1857 Unmarked lines are exempt from recalculation with `C-u C-c *'.
1858 All lines that should be recalculated should be marked with `#' or
1862 Do not export this line. Useful for lines that contain the
1863 narrowing `<N>' markers.
1865 Finally, just to whet your appetite on what can be done with the
1866 fantastic `calc' package, here is a table that computes the Taylor
1867 series of degree `n' at location `x' for a couple of functions
1868 (homework: try that with Excel :-)
1870 |---+-------------+---+-----+--------------------------------------|
1871 | | Func | n | x | Result |
1872 |---+-------------+---+-----+--------------------------------------|
1873 | # | exp(x) | 1 | x | 1 + x |
1874 | # | exp(x) | 2 | x | 1 + x + x^2 / 2 |
1875 | # | exp(x) | 3 | x | 1 + x + x^2 / 2 + x^3 / 6 |
1876 | # | x^2+sqrt(x) | 2 | x=0 | x*(0.5 / 0) + x^2 (2 - 0.25 / 0) / 2 |
1877 | # | x^2+sqrt(x) | 2 | x=1 | 2 + 2.5 x - 2.5 + 0.875 (x - 1)^2 |
1878 | * | tan(x) | 3 | x | 0.0175 x + 1.77e-6 x^3 |
1879 |---+-------------+---+-----+--------------------------------------|
1880 #+TBLFM: $5=taylor($2,$4,$3);n3
1883 File: org, Node: Hyperlinks, Next: TODO items, Prev: Tables, Up: Top
1888 Just like HTML, Org-mode provides links inside a file, and external
1889 links to other files, Usenet articles, emails, and much more.
1893 * Link format:: How links in Org-mode are formatted
1894 * Internal links:: Links to other places in the current file
1895 * External links:: URL-like links to the world
1896 * Handling links:: Creating, inserting and following
1897 * Using links outside Org-mode:: Linking from my C source code?
1898 * Link abbreviations:: Shortcuts for writing complex links
1899 * Search options:: Linking to a specific location
1900 * Custom searches:: When the default search is not enough
1901 * Remember:: Org-trees store quick notes
1904 File: org, Node: Link format, Next: Internal links, Prev: Hyperlinks, Up: Hyperlinks
1909 Org-mode will recognize plain URL-like links and activate them as
1910 clickable links. The general link format, however, looks like this:
1912 [[link][description]] or alternatively [[link]]
1914 Once a link in the buffer is complete (all brackets present),
1915 Org-mode will change the display so that `description' is displayed
1916 instead of `[[link][description]]' and `link' is displayed instead of
1917 `[[link]]'. Links will be highlighted in the face `org-link', which by
1918 default is an underlined face. You can directly edit the visible part
1919 of a link. Note that this can be either the `link' part (if there is
1920 no description) or the `description' part. To edit also the invisible
1921 `link' part, use `C-c C-l' with the cursor on the link.
1923 If you place the cursor at the beginning or just behind the end of
1924 the displayed text and press <BACKSPACE>, you will remove the
1925 (invisible) bracket at that location. This makes the link incomplete
1926 and the internals are again displayed as plain text. Inserting the
1927 missing bracket hides the link internals again. To show the internal
1928 structure of all links, use the menu entry `Org->Hyperlinks->Literal
1932 File: org, Node: Internal links, Next: External links, Prev: Link format, Up: Hyperlinks
1937 If the link does not look like a URL, it is considered to be internal in
1938 the current file. Links such as `[[My Target]]' or `[[My Target][Find
1939 my target]]' lead to a text search in the current file. The link can
1940 be followed with `C-c C-o' when the cursor is on the link, or with a
1941 mouse click (*note Handling links::). The preferred match for such a
1942 link is a dedicated target: the same string in double angular brackets.
1943 Targets may be located anywhere; sometimes it is convenient to put
1944 them into a comment line. For example
1948 In HTML export (*note HTML export::), such targets will become named
1949 anchors for direct access through `http' links(1).
1951 If no dedicated target exists, Org-mode will search for the words in
1952 the link. In the above example the search would be for `my target'.
1953 Links starting with a star like `*My Target' restrict the search to
1954 headlines. When searching, Org-mode will first try an exact match, but
1955 then move on to more and more lenient searches. For example, the link
1956 `[[*My Targets]]' will find any of the following:
1959 ** TODO my targets are bright
1960 ** my 20 targets are
1962 To insert a link targeting a headline, in-buffer completion can be
1963 used. Just type a star followed by a few optional letters into the
1964 buffer and press `M-<TAB>'. All headlines in the current buffer will be
1965 offered as completions. *Note Handling links::, for more commands
1968 Following a link pushes a mark onto Org-mode's own mark ring. You
1969 can return to the previous position with `C-c &'. Using this command
1970 several times in direct succession goes back to positions recorded
1975 * Radio targets:: Make targets trigger links in plain text.
1977 ---------- Footnotes ----------
1979 (1) Note that text before the first headline is usually not
1980 exported, so the first such target should be after the first headline.
1983 File: org, Node: Radio targets, Prev: Internal links, Up: Internal links
1988 Org-mode can automatically turn any occurrences of certain target names
1989 in normal text into a link. So without explicitly creating a link, the
1990 text connects to the target radioing its position. Radio targets are
1991 enclosed by triple angular brackets. For example, a target `<<<My
1992 Target>>>' causes each occurrence of `my target' in normal text to
1993 become activated as a link. The Org-mode file is scanned automatically
1994 for radio targets only when the file is first loaded into Emacs. To
1995 update the target list during editing, press `C-c C-c' with the cursor
1999 File: org, Node: External links, Next: Handling links, Prev: Internal links, Up: Hyperlinks
2004 Org-mode supports links to files, websites, Usenet and email messages,
2005 and BBDB database entries. External links are URL-like locators. They
2006 start with a short identifying string followed by a colon. There can be
2007 no space after the colon. The following list shows examples for each
2010 http://www.astro.uva.nl/~dominik on the web
2011 file:/home/dominik/images/jupiter.jpg file, absolute path
2012 file:papers/last.pdf file, relative path
2013 news:comp.emacs Usenet link
2014 mailto:adent@galaxy.net Mail link
2015 vm:folder VM folder link
2016 vm:folder#id VM message link
2017 vm://myself@some.where.org/folder#id VM on remote machine
2018 wl:folder WANDERLUST folder link
2019 wl:folder#id WANDERLUST message link
2020 mhe:folder MH-E folder link
2021 mhe:folder#id MH-E message link
2022 rmail:folder RMAIL folder link
2023 rmail:folder#id RMAIL message link
2024 gnus:group GNUS group link
2025 gnus:group#id GNUS article link
2026 bbdb:Richard Stallman BBDB link
2027 shell:ls *.org A shell command
2028 elisp:(find-file-other-frame "Elisp.org") An elisp form to evaluate
2030 A link should be enclosed in double brackets and may contain a
2031 descriptive text to be displayed instead of the url (*note Link
2032 format::), for example:
2034 [[http://www.gnu.org/software/emacs/][GNU Emacs]]
2036 If the description is a file name or URL that points to an image, HTML
2037 export (*note HTML export::) will inline the image as a clickable
2038 button. If there is no description at all and the link points to an
2039 image, that image will be inlined into the exported HTML file.
2041 Org-mode also finds external links in the normal text and activates
2042 them as links. If spaces must be part of the link (for example in
2043 `bbdb:Richard Stallman'), or if you need to remove ambiguities about
2044 the end of the link, enclose them in angular brackets.
2047 File: org, Node: Handling links, Next: Using links outside Org-mode, Prev: External links, Up: Hyperlinks
2052 Org-mode provides methods to create a link in the correct syntax, to
2053 insert it into an org-mode file, and to follow the link.
2056 Store a link to the current location. This is a _global_ command
2057 which can be used in any buffer to create a link. The link will be
2058 stored for later insertion into an Org-mode buffer (see below).
2059 For Org-mode files, if there is a `<<target>>' at the cursor, the
2060 link points to the target. Otherwise it points to the current
2061 headline. For VM, RMAIL, WANDERLUST, MH-E, GNUS and BBDB buffers,
2062 the link will indicate the current article/entry. For W3 and W3M
2063 buffers, the link goes to the current URL. For any other files,
2064 the link will point to the file, with a search string (*note
2065 Search options::) pointing to the contents of the current line.
2066 If there is an active region, the selected words will form the
2067 basis of the search string. If the automatically created link is
2068 not working correctly or accurately enough, you can write custom
2069 functions to select the search string and to do the search for
2070 particular file types - see *Note Custom searches::. The key
2071 binding `C-c l' is only a suggestion - see *Note Installation::.
2074 Insert a link. This prompts for a link to be inserted into the
2075 buffer. You can just type a link, using text for an internal
2076 link, or one of the link type prefixes mentioned in the examples
2077 above. All links stored during the current session are part of
2078 the history for this prompt, so you can access them with <up> and
2079 <down>. Completion, on the other hand, will help you to insert
2080 valid link prefixes like `http:' or `ftp:', including the prefixes
2081 defined through link abbreviations (*note Link abbreviations::).
2082 The link will be inserted into the buffer(1), along with a
2083 descriptive text. If some text was selected when this command is
2084 called, the selected text becomes the default description.
2085 Note that you don't have to use this command to insert a link.
2086 Links in Org-mode are plain text, and you can type or paste them
2087 straight into the buffer. By using this command, the links are
2088 automatically enclosed in double brackets, and you will be asked
2089 for the optional descriptive text.
2092 When `C-c C-l' is called with a `C-u' prefix argument, a link to a
2093 file will be inserted and you may use file name completion to
2094 select the name of the file. The path to the file is inserted
2095 relative to the directory of the current org file, if the linked
2096 file is in the current directory or in a subdirectory of it, or if
2097 the path is written relative to the current directory using `../'.
2098 Otherwise an absolute path is used, if possible with `~/' for
2099 your home directory. You can force an absolute path with two
2102 `C-c C-l (with cursor on existing link)'
2103 When the cursor is on an existing link, `C-c C-l' allows you to
2104 edit the link and description parts of the link.
2107 Open link at point. This will launch a web browser for URLs (using
2108 `browse-url-at-point'), run vm/mh-e/wanderlust/rmail/gnus/bbdb for
2109 the corresponding links, and execute the command in a shell link.
2110 When the cursor is on an internal link, this commands runs the
2111 corresponding search. When the cursor is on a TAG list in a
2112 headline, it creates the corresponding TAGS view. If the cursor
2113 is on a time stamp, it compiles the agenda for that date.
2114 Furthermore, it will visit text and remote files in `file:' links
2115 with Emacs and select a suitable application for local non-text
2116 files. Classification of files is based on file extension only.
2117 See option `org-file-apps'. If you want to override the default
2118 application and visit the file with Emacs, use a `C-u' prefix.
2122 On links, `mouse-2' will open the link just as `C-c C-o' would.
2123 Under Emacs 22, also `mouse-1' will follow a link.
2126 Like `mouse-2', but force file links to be opened with Emacs, and
2127 internal links to be displayed in another window(2).
2130 Push the current position onto the mark ring, to be able to return
2131 easily. Commands following an internal link do this automatically.
2134 Jump back to a recorded position. A position is recorded by the
2135 commands following internal links, and by `C-c %'. Using this
2136 command several times in direct succession moves through a ring of
2137 previously recorded positions.
2141 Move forward/backward to the next link in the buffer. At the
2142 limit of the buffer, the search fails once, and then wraps around.
2143 The key bindings for this are really too long, you might want to
2144 bind this also to `C-n' and `C-p'
2145 (add-hook 'org-load-hook
2147 (define-key 'org-mode-map "\C-n" 'org-next-link)
2148 (define-key 'org-mode-map "\C-p" 'org-previous-link)))
2150 ---------- Footnotes ----------
2152 (1) After insertion of a stored link, the link will be removed from
2153 the list of stored links. To keep it in the list later use, use a
2154 triple `C-u' prefix to `C-c C-l', or configure the option
2155 `org-keep-stored-link-after-insertion'.
2157 (2) See the variable `org-display-internal-link-with-indirect-buffer'
2160 File: org, Node: Using links outside Org-mode, Next: Link abbreviations, Prev: Handling links, Up: Hyperlinks
2162 4.5 Using links outside Org-mode
2163 ================================
2165 You can insert and follow links that have Org-mode syntax not only in
2166 Org-mode, but in any Emacs buffer. For this, you should create two
2167 global commands, like this (please select suitable global keys
2170 (global-set-key "\C-c L" 'org-insert-link-global)
2171 (global-set-key "\C-c o" 'org-open-at-point-global)
2174 File: org, Node: Link abbreviations, Next: Search options, Prev: Using links outside Org-mode, Up: Hyperlinks
2176 4.6 Link abbreviations
2177 ======================
2179 Long URLs can be cumbersome to type, and often many similar links are
2180 needed in a document. For this you can use link abbreviations. An
2181 abbreviated link looks like this
2183 [[linkword:tag][description]]
2185 where the tag is optional. Such abbreviations are resolved according to
2186 the information in the variable `org-link-abbrev-alist' that relates
2187 the linkwords to replacement text. Here is an example:
2189 (setq org-link-abbrev-alist
2190 '(("bugzilla" . "http://10.1.2.9/bugzilla/show_bug.cgi?id=")
2191 ("google" . "http://www.google.com/search?q=")
2192 ("ads" . "http://adsabs.harvard.edu/cgi-bin/
2193 nph-abs_connect?author=%s&db_key=AST")))
2195 If the replacement text contains the string `%s', it will be
2196 replaced with the tag. Otherwise the tag will be appended to the string
2197 in order to create the link. You may also specify a function that will
2198 be called with the tag as the only argument to create the link.
2200 With the above setting, you could link to a specific bug with
2201 `[[bugzilla:129]]', search the web for `OrgMode' with
2202 `[[google:OrgMode]]' and find out what the Org-mode author is doing
2203 besides Emacs hacking with `[[ads:Dominik,C]]'.
2205 If you need special abbreviations just for a single Org-mode buffer,
2206 you can define them in the file with
2208 #+LINK: bugzilla http://10.1.2.9/bugzilla/show_bug.cgi?id=
2209 #+LINK: google http://www.google.com/search?q=%s
2211 In-buffer completion *note Completion:: can be used after `[' to
2212 complete link abbreviations.
2215 File: org, Node: Search options, Next: Custom searches, Prev: Link abbreviations, Up: Hyperlinks
2217 4.7 Search options in file links
2218 ================================
2220 File links can contain additional information to make Emacs jump to a
2221 particular location in the file when following a link. This can be a
2222 line number or a search option after a double(1) colon. For example,
2223 when the command `C-c l' creates a link (*note Handling links::) to a
2224 file, it encodes the words in the current line as a search string that
2225 can be used to find this line back later when following the link with
2228 Here is the syntax of the different ways to attach a search to a file
2229 link, together with an explanation:
2231 [[file:~/code/main.c::255]]
2232 [[file:~/xx.org::My Target]]
2233 [[file:~/xx.org::*My Target]]
2234 [[file:~/xx.org::/regexp/]]
2240 Search for a link target `<<My Target>>', or do a text search for
2241 `my target', similar to the search in internal links, see *Note
2242 Internal links::. In HTML export (*note HTML export::), such a
2243 file link will become an HTML reference to the corresponding named
2244 anchor in the linked file.
2247 In an Org-mode file, restrict search to headlines.
2250 Do a regular expression search for `regexp'. This uses the Emacs
2251 command `occur' to list all matches in a separate window. If the
2252 target file is in Org-mode, `org-occur' is used to create a sparse
2253 tree with the matches.
2255 As a degenerate case, a file link with an empty file name can be used
2256 to search the current file. For example, `[[file:::find me]]' does a
2257 search for `find me' in the current file, just as `[[find me]]' would.
2259 ---------- Footnotes ----------
2261 (1) For backward compatibility, line numbers can also follow a
2265 File: org, Node: Custom searches, Next: Remember, Prev: Search options, Up: Hyperlinks
2270 The default mechanism for creating search strings and for doing the
2271 actual search related to a file link may not work correctly in all
2272 cases. For example, BibTeX database files have many entries like
2273 `year="1993"' which would not result in good search strings, because
2274 the only unique identification for a BibTeX entry is the citation key.
2276 If you come across such a problem, you can write custom functions to
2277 set the right search string for a particular file type, and to do the
2278 search for the string in the file. Using `add-hook', these functions
2279 need to be added to the hook variables
2280 `org-create-file-search-functions' and
2281 `org-execute-file-search-functions'. See the docstring for these
2282 variables for more information. Org-mode actually uses this mechanism
2283 for BibTeX database files, and you can use the corresponding code as an
2284 implementation example. Search for `BibTeX links' in the source file.
2287 File: org, Node: Remember, Prev: Custom searches, Up: Hyperlinks
2292 Another way to create org entries with links to other files is through
2293 the remember package by John Wiegley. Remember lets you store quick
2294 notes with little interruption of your work flow. See
2295 `http://www.emacswiki.org/cgi-bin/wiki/RememberMode' for more
2296 information. The notes produced by Remember can be stored in different
2297 ways, and Org-mode files are a good target. Org-mode significantly
2298 expands the possibilities of remember: You may define templates for
2299 different note types, and to associate target files and headlines with
2300 specific templates. It also allows you to select the location where a
2301 note should be stored interactively, on the fly.
2305 * Setting up remember:: Some code for .emacs to get things going
2306 * Remember templates:: Define the outline of different note types
2307 * Storing notes:: Directly get the note to where it belongs
2310 File: org, Node: Setting up remember, Next: Remember templates, Prev: Remember, Up: Remember
2312 4.9.1 Setting up remember
2313 -------------------------
2315 The following customization will tell remember to use org files as
2316 target, and to create annotations compatible with Org-mode links.
2318 (setq org-directory "~/path/to/my/orgfiles/")
2319 (setq org-default-notes-file "~/.notes")
2320 (setq remember-annotation-functions '(org-remember-annotation))
2321 (setq remember-handler-functions '(org-remember-handler))
2322 (add-hook 'remember-mode-hook 'org-remember-apply-template)
2325 File: org, Node: Remember templates, Next: Storing notes, Prev: Setting up remember, Up: Remember
2327 4.9.2 Remember templates
2328 ------------------------
2330 In combination with Org-mode, you can use templates to generate
2331 different types of remember notes. For example, if you would like to
2332 use one template to create general TODO entries, another one for
2333 journal entries, and a third one for collecting random ideas, you could
2336 (setq org-remember-templates
2337 '((?t "* TODO %?\n %i\n %a" "~/org/TODO.org")
2338 (?j "* %U %?\n\n %i\n %a" "~/org/JOURNAL.org")
2339 (?i "* %^{Title}\n %i\n %a" "~/org/JOURNAL.org" "New Ideas")))
2341 In these entries, the character specifies how to select the template.
2342 The first string specifies the template. Two more (optional) strings
2343 give the file in which, and the headline under which the new note
2344 should be stored. The file defaults (if not present or `nil') to
2345 `org-default-notes-file', the heading to
2346 `org-remember-default-headline'. Both defaults help to get to the
2347 storing location quickly, but you can change the location interactively
2348 while storing the note.
2350 When you call `M-x remember' (or `M-x org-remember') to remember
2351 something, org will prompt for a key to select the template (if you have
2352 more than one template) and then prepare the buffer like
2354 [[file:link to where you called remember]]
2358 * [2006-03-21 Tue 15:37]
2360 [[file:link to where you called remember]]
2362 During expansion of the template, special `%'-escapes allow dynamic
2363 insertion of content:
2364 %^{prompt} prompt the user for a string and replace this sequence with it.
2365 %t time stamp, date only
2366 %T time stamp with date and time
2367 %u, %U like the above, but inactive time stamps
2368 %^t like `%t', but prompt for date. Similarly `%^T', `%^u', `%^U'
2369 You may define a prompt like `%^{Birthday}t'
2370 %n user name (taken from `user-full-name')
2371 %a annotation, normally the link created with `org-store-link'
2372 %i initial content, the region when remember is called with C-u.
2373 The entire text will be indented like `%i' itself.
2374 %^g prompt for tags, with completion on tags in target file.
2375 %^G prompt for tags, with completion all tags in all agenda files.
2376 %:keyword specific information for certain link types, see below
2378 For specific link types, the following keywords will be defined:
2380 Link type | Available keywords
2381 -------------------+----------------------------------------------
2382 bbdb | %:name %:company
2383 vm, wl, mh, rmail | %:type %:subject %:message-id
2384 | %:from %:fromname %:fromaddress
2385 | %:to %:toname %:toaddress
2386 | %:fromto (either "to NAME" or "from NAME")(1)
2387 gnus | %:group, for messages also all email fields
2389 info | %:file %:node
2392 To place the cursor after template expansion use:
2394 %? After completing the template, position cursor here.
2396 If you change you mind about which template to use, call `org-remember'
2397 in the remember buffer. You may then select a new template that will
2398 be filled with the previous context information.
2400 ---------- Footnotes ----------
2402 (1) This will always be the other, not the user. See the variable
2403 `org-from-is-user-regexp'.
2406 File: org, Node: Storing notes, Prev: Remember templates, Up: Remember
2411 When you are finished preparing a note with remember, you have to press
2412 `C-c C-c' to file the note away. The handler first prompts for a
2413 target file - if you press <RET>, the value specified for the template
2414 is used. Then the command offers the headings tree of the selected
2415 file, with the cursor position at the default headline (if you had
2416 specified one in the template). You can either immediately press <RET>
2417 to get the note placed there. Or you can use the following keys to
2418 find a better location:
2419 <TAB> Cycle visibility.
2420 <down> / <up> Next/previous visible headline.
2421 n / p Next/previous visible headline.
2422 f / b Next/previous headline same level.
2424 Pressing <RET> or <left> or <right> then leads to the following
2427 Cursor Key Note gets inserted
2429 buffer-start <RET> as level 2 heading at end of file
2430 on headline <RET> as sublevel of the heading at cursor
2431 <left>/<right>as same level, before/after current heading
2432 not on <RET> at cursor position, level taken from context.
2435 So a fast way to store the note to its default location is to press
2436 `C-c C-c <RET> <RET>'. Even shorter would be `C-u C-c C-c', which does
2437 the same without even asking for a file or showing the tree.
2439 Before inserting the text into a tree, the function ensures that the
2440 text has a headline, i.e. a first line that starts with a `*'. If not,
2441 a headline is constructed from the current date and some additional
2442 data. If the variable `org-adapt-indentation' is non-nil, the entire
2443 text is also indented so that it starts in the same column as the
2444 headline (after the asterisks).
2447 File: org, Node: TODO items, Next: Tags, Prev: Hyperlinks, Up: Top
2452 Org-mode does not maintain TODO lists as a separate document. TODO
2453 items are an integral part of the notes file, because TODO items
2454 usually come up while taking notes! With Org-mode, you simply mark any
2455 entry in a tree as being a TODO item. In this way, the information is
2456 not duplicated, and the entire context from which the item emerged is
2457 always present when you check.
2459 Of course, this technique causes TODO items to be scattered
2460 throughout your file. Org-mode provides methods to give you an
2461 overview over all things you have to do.
2465 * TODO basics:: Marking and displaying TODO entries
2466 * TODO extensions:: Workflow and assignments
2467 * Priorities:: Some things are more important than others
2468 * Breaking down tasks:: Splitting a task into manageable pieces
2469 * Checkboxes:: Tick-off lists
2472 File: org, Node: TODO basics, Next: TODO extensions, Prev: TODO items, Up: TODO items
2474 5.1 Basic TODO functionality
2475 ============================
2477 Any headline can become a TODO item by starting it with the word TODO,
2480 *** TODO Write letter to Sam Fortune
2482 The most important commands to work with TODO entries are:
2485 Rotate the TODO state of the current item among
2487 ,-> (unmarked) -> TODO -> DONE --.
2488 '--------------------------------'
2490 The same rotation can also be done "remotely" from the timeline and
2491 agenda buffers with the `t' command key (*note Agenda commands::).
2495 Select the following/preceding TODO state, similar to cycling.
2496 Mostly useful if more than two TODO states are possible (*note
2500 Use the fast tag interface to quickly and directly select a
2501 specific TODO state. For this you need to assign keys to TODO
2503 #+SEQ_TODO: TODO(t) STARTED(s) WAITING(w) | DONE(d)
2504 See *Note Per file keywords:: and *Note Setting tags:: for more
2508 View TODO items in a _sparse tree_ (*note Sparse trees::). Folds
2509 the entire buffer, but shows all TODO items and the headings
2510 hierarchy above them. With prefix arg, search for a specific
2511 TODO. You will be prompted for the keyword, and you can also give
2512 a list of keywords like `kwd1|kwd2|...'. With numerical prefix N,
2513 show the tree for the Nth keyword in the variable
2514 `org-todo-keywords'. With two prefix args, find all TODO and DONE
2518 Show the global TODO list. This collects the TODO items from all
2519 agenda files (*note Agenda views::) into a single buffer. The
2520 buffer is in `agenda-mode', so there are commands to examine and
2521 manipulate the TODO entries directly from that buffer (*note
2522 Agenda commands::). *Note Global TODO list::, for more
2526 Insert a new TODO entry below the current one.
2529 File: org, Node: TODO extensions, Next: Priorities, Prev: TODO basics, Up: TODO items
2531 5.2 Extended use of TODO keywords
2532 =================================
2534 The default implementation of TODO entries is just two states: TODO and
2535 DONE. You can use the TODO feature for more complicated things by
2536 configuring the variable `org-todo-keywords'. With special setup, the
2537 TODO keyword system can work differently in different files.
2539 Note that tags are another way to classify headlines in general and
2540 TODO items in particular (*note Tags::).
2544 * Workflow states:: From TODO to DONE in steps
2545 * TODO types:: I do this, Fred the rest
2546 * Multiple sets in one file:: Mixing it all, and still finding your way
2547 * Per file keywords:: Different files, different requirements
2550 File: org, Node: Workflow states, Next: TODO types, Prev: TODO extensions, Up: TODO extensions
2552 5.2.1 TODO keywords as workflow states
2553 --------------------------------------
2555 You can use TODO keywords to indicate different _sequential_ states in
2556 the process of working on an item, for example(1):
2558 (setq org-todo-keywords
2559 '((sequence "TODO" "FEEDBACK" "VERIFY" "|" "DONE" "DELEGATED")))
2561 The vertical bar separates the TODO keywords (states that _need
2562 action_) from the DONE states (which need _no further action_. If you
2563 don't provide the separator bar, the last state is used as the DONE
2564 state. With this setup, the command `C-c C-t' will cycle an entry from
2565 TODO to FEEDBACK, then to VERIFY, and finally to DONE and DELEGATED.
2566 You may also use a prefix argument to quickly select a specific state.
2567 For example `C-3 C-c C-t' will change the state immediately to VERIFY.
2568 If you define many keywords, you can use in-buffer completion (see
2569 *Note Completion::) to insert these words into the buffer. Changing a
2570 todo state can be logged with a timestamp, see *Note Tracking TODO
2571 state changes:: for more information.
2573 ---------- Footnotes ----------
2575 (1) Changing this variable only becomes effective after restarting
2576 Org-mode in a buffer.
2579 File: org, Node: TODO types, Next: Multiple sets in one file, Prev: Workflow states, Up: TODO extensions
2581 5.2.2 TODO keywords as types
2582 ----------------------------
2584 The second possibility is to use TODO keywords to indicate different
2585 _types_ of action items. For example, you might want to indicate that
2586 items are for "work" or "home". Or, when you work with several people
2587 on a single project, you might want to assign action items directly to
2588 persons, by using their names as TODO keywords. This would be set up
2591 (setq org-todo-keywords '((type "Fred" "Sara" "Lucy" "|" "DONE")))
2593 In this case, different keywords do not indicate a sequence, but
2594 rather different types. So the normal work flow would be to assign a
2595 task to a person, and later to mark it DONE. Org-mode supports this
2596 style by adapting the workings of the command `C-c C-t'(1). When used
2597 several times in succession, it will still cycle through all names, in
2598 order to first select the right type for a task. But when you return
2599 to the item after some time and execute `C-c C-t' again, it will switch
2600 from any name directly to DONE. Use prefix arguments or completion to
2601 quickly select a specific name. You can also review the items of a
2602 specific TODO type in a sparse tree by using a numeric prefix to `C-c
2603 C-v'. For example, to see all things Lucy has to do, you would use
2604 `C-3 C-c C-v'. To collect Lucy's items from all agenda files into a
2605 single buffer, you would use the prefix arg as well when creating the
2606 global todo list: `C-3 C-c t'.
2608 ---------- Footnotes ----------
2610 (1) This is also true for the `t' command in the timeline and agenda
2614 File: org, Node: Multiple sets in one file, Next: Per file keywords, Prev: TODO types, Up: TODO extensions
2616 5.2.3 Multiple keyword sets in one file
2617 ---------------------------------------
2619 Sometimes you may want to use different sets of TODO keywords in
2620 parallel. For example, you may want to have the basic `TODO'/`DONE',
2621 but also a workflow for bug fixing, and a separate state indicating
2622 that an item has been canceled (so it is not DONE, but also does not
2623 require action). Your setup would then look like this:
2625 (setq org-todo-keywords
2626 '((sequence "TODO" "|" "DONE")
2627 (sequence "REPORT" "BUG" "KNOWNCAUSE" "|" "FIXED")
2628 (sequence "|" "CANCELED")))
2630 The keywords should all be different, this helps Org-mode to keep
2631 track of which subsequence should be used for a given entry. In this
2632 setup, `C-c C-t' only operates within a subsequence, so it switches from
2633 `DONE' to (nothing) to `TODO', and from `FIXED' to (nothing) to
2634 `REPORT'. Therefore you need a mechanism to initially select the
2635 correct sequence. Besides the obvious ways like typing a keyword or
2636 using completion, you may also apply the following commands:
2640 These keys jump from one TODO subset to the next. In the above
2641 example, `C-S-<right>' would jump from `TODO' or `DONE' to
2642 `REPORT', and any of the words in the second row to `CANCELED'.
2646 `S-<<left>>' and `S-<<right>>' and walk through _all_ keywords
2647 from all sets, so for example `S-<<right>>' would switch from
2648 `DONE' to `REPORT' in the example above.
2651 File: org, Node: Per file keywords, Prev: Multiple sets in one file, Up: TODO extensions
2653 5.2.4 Setting up keywords for individual files
2654 ----------------------------------------------
2656 It can be very useful to use different aspects of the TODO mechanism in
2657 different files. For file-local settings, you need to add special lines
2658 to the file which set the keywords and interpretation for that file
2659 only. For example, to set one of the two examples discussed above, you
2660 need one of the following lines, starting in column zero anywhere in the
2663 #+SEQ_TODO: TODO FEEDBACK VERIFY | DONE CANCELED
2665 #+TYP_TODO: Fred Sara Lucy Mike | DONE
2667 A setup for using several sets in parallel would be:
2669 #+SEQ_TODO: TODO | DONE
2670 #+SEQ_TODO: REPORT BUG KNOWNCAUSE | FIXED
2671 #+SEQ_TODO: | CANCELED
2673 To make sure you are using the correct keyword, type `#+' into the
2674 buffer and then use `M-<TAB>' completion.
2676 Remember that the keywords after the vertical bar (or the last
2677 keyword if no bar is there) must always mean that the item is DONE
2678 (although you may use a different word). After changing one of these
2679 lines, use `C-c C-c' with the cursor still in the line to make the
2680 changes known to Org-mode(1).
2682 ---------- Footnotes ----------
2684 (1) Org-mode parses these lines only when Org-mode is activated
2685 after visiting a file. `C-c C-c' with the cursor in a line starting
2686 with `#+' is simply restarting Org-mode for the current buffer.
2689 File: org, Node: Priorities, Next: Breaking down tasks, Prev: TODO extensions, Up: TODO items
2694 If you use Org-mode extensively to organize your work, you may end up
2695 with a number of TODO entries so large that you'd like to prioritize
2696 them. This can be done by placing a _priority cookie_ into the
2699 *** TODO [#A] Write letter to Sam Fortune
2701 With its standard setup, Org-mode supports priorities `A', `B', and
2702 `C'. `A' is the highest priority. An entry without a cookie is
2703 treated as priority `B'. Priorities make a difference only in the
2704 agenda (*note Weekly/Daily agenda::).
2707 Set the priority of the current headline. The command prompts for
2708 a priority character `A', `B' or `C'. When you press <SPC>
2709 instead, the priority cookie is removed from the headline. The
2710 priorities can also be changed "remotely" from the timeline and
2711 agenda buffer with the `,' command (*note Agenda commands::).
2715 Increase/decrease priority of current headline. Note that these
2716 keys are also used to modify time stamps (*note Creating
2717 timestamps::). Furthermore, these keys are also used by CUA-mode
2718 (*note Conflicts::).
2720 You can change the range of allowed priorities by setting the
2721 variables `org-highest-priority', `org-lowest-priority', and
2722 `org-default-priority'. For an individual buffer, you may set these
2723 values (highest, lowest, default) like this (please make sure that the
2724 highest priority is earlier in the alphabet than the lowest priority):
2729 File: org, Node: Breaking down tasks, Next: Checkboxes, Prev: Priorities, Up: TODO items
2731 5.4 Breaking tasks down into subtasks
2732 =====================================
2734 It is often advisable to break down large tasks into smaller, manageable
2735 subtasks. You can do this by creating an outline tree below a TODO
2736 item, with detailed subtasks on the tree(1). Another possibility is
2737 the use of checkboxes to identify (a hierarchy of) a large number of
2738 subtasks (*note Checkboxes::).
2740 ---------- Footnotes ----------
2742 (1) To keep subtasks out of the global TODO list, see the
2743 `org-agenda-todo-list-sublevels'.
2746 File: org, Node: Checkboxes, Prev: Breaking down tasks, Up: TODO items
2751 Every item in a plain list (*note Plain lists::) can be made a checkbox
2752 by starting it with the string `[ ]'. This feature is similar to TODO
2753 items (*note TODO items::), but more lightweight. Checkboxes are not
2754 included into the global TODO list, so they are often great to split a
2755 task into a number of simple steps. Or you can use them in a shopping
2756 list. To toggle a checkbox, use `C-c C-c', or try Piotr Zielinski's
2757 `org-mouse.el'. Here is an example of a checkbox list.
2759 * TODO Organize party [3/6]
2765 - [ ] think about what music to play
2766 - [X] talk to the neighbors
2768 The `[3/6]' and `[1/3]' in the first and second line are cookies
2769 indicating how many checkboxes are present in this entry, and how many
2770 of them have been checked off. This can give you an idea on how many
2771 checkboxes remain, even without opening a folded entry. The cookies
2772 can be placed into a headline or into (the first line of) a plain list
2773 item. Each cookie covers all checkboxes structurally below that
2774 headline/item. You have to insert the cookie yourself by typing either
2775 `[/]' or `[%]'. In the first case you get an `n out of m' result, in
2776 the second case you get information about the percentage of checkboxes
2777 checked (in the above example, this would be `[50%]' and `[33%],
2780 The following commands work with checkboxes:
2783 Toggle checkbox at point. With prefix argument, set it to `[-]',
2784 which is considered to be an intermediate state.
2787 Toggle checkbox at point.
2788 - If there is an active region, toggle the first checkbox in
2789 the region and set all remaining boxes to the same status as
2790 the first. If you want to toggle all boxes in the region
2791 independently, use a prefix argument.
2793 - If the cursor is in a headline, toggle checkboxes in the
2794 region between this headline and the next (so _not_ the
2797 - If there is no active region, just toggle the checkbox at
2801 Insert a new item with a checkbox. This works only if the cursor
2802 is already in a plain list item (*note Plain lists::).
2805 Update the checkbox statistics in the current outline entry. When
2806 called with a `C-u' prefix, update the entire file. Checkbox
2807 statistic cookies are updated automatically if you toggle
2808 checkboxes with `C-c C-c' and make new ones with `M-S-<RET>'. If
2809 you delete boxes or add/change them by hand, use this command to
2810 get things back into synch. Or simply toggle any checkbox twice
2814 File: org, Node: Tags, Next: Properties and columns, Prev: TODO items, Up: Top
2819 If you wish to implement a system of labels and contexts for
2820 cross-correlating information, an excellent way is to assign tags to
2821 headlines. Org-mode has extensive support for using tags.
2823 Every headline can contain a list of tags, at the end of the
2824 headline. Tags are normal words containing letters, numbers, `_', and
2825 `@'. Tags must be preceded and followed by a single colon; like
2826 `:WORK:'. Several tags can be specified like `:WORK:URGENT:'.
2830 * Tag inheritance:: Tags use the tree structure of the outline
2831 * Setting tags:: How to assign tags to a headline
2832 * Tag searches:: Searching for combinations of tags
2835 File: org, Node: Tag inheritance, Next: Setting tags, Prev: Tags, Up: Tags
2840 Tags make use of the hierarchical structure of outline trees. If a
2841 heading has a certain tag, all subheadings will inherit the tag as
2842 well. For example, in the list
2844 * Meeting with the French group :WORK:
2845 ** Summary by Frank :BOSS:NOTES:
2846 *** TODO Prepare slides for him :ACTION:
2848 the final heading will have the tags `:WORK:', `:BOSS:', `:NOTES:', and
2849 `:ACTION:'. When executing tag searches and Org-mode finds that a
2850 certain headline matches the search criterion, it will not check any
2851 sublevel headline, assuming that these likely also match, and that the
2852 list of matches can become very long. This may not be what you want,
2853 however, and you can influence inheritance and searching using the
2854 variables `org-use-tag-inheritance' and `org-tags-match-list-sublevels'.
2857 File: org, Node: Setting tags, Next: Tag searches, Prev: Tag inheritance, Up: Tags
2862 Tags can simply be typed into the buffer at the end of a headline.
2863 After a colon, `M-<TAB>' offers completion on tags. There is also a
2864 special command for inserting tags:
2867 Enter new tags for the current headline. Org-mode will either
2868 offer completion or a special single-key interface for setting
2869 tags, see below. After pressing <RET>, the tags will be inserted
2870 and aligned to `org-tags-column'. When called with a `C-u'
2871 prefix, all tags in the current buffer will be aligned to that
2872 column, just to make things look nice. TAGS are automatically
2873 realigned after promotion, demotion, and TODO state changes (*note
2876 Org will support tag insertion based on a _list of tags_. By
2877 default this list is constructed dynamically, containing all tags
2878 currently used in the buffer. You may also globally specify a hard list
2879 of tags with the variable `org-tag-alist'. Finally you can set the
2880 default tags for a given file with lines like
2882 #+TAGS: @WORK @HOME @TENNISCLUB
2883 #+TAGS: Laptop Car PC Sailboat
2885 If you have globally defined your preferred set of tags using the
2886 variable `org-tag-alist', but would like to use a dynamic tag list in a
2887 specific file: Just add an empty TAGS option line to that file:
2891 The default support method for entering tags is minibuffer
2892 completion. However, Org-mode also implements a much better method:
2893 _fast tag selection_. This method allows to select and deselect tags
2894 with a single key per tag. To function efficiently, you should assign
2895 unique keys to most tags. This can be done globally with
2897 (setq org-tag-alist '(("@WORK" . ?w) ("@HOME" . ?h) ("Laptop" . ?l)))
2899 or on a per-file basis with
2901 #+TAGS: @WORK(w) @HOME(h) @TENNISCLUB(t) Laptop(l) PC(p)
2903 You can also group together tags that are mutually exclusive. With
2906 #+TAGS: { @WORK(w) @HOME(h) @TENNISCLUB(t) } Laptop(l) PC(p)
2908 you indicate that at most one of `@WORK', `@HOME', and `@TENNISCLUB'
2911 Don't forget to press `C-c C-c' with the cursor in one of these lines
2912 to activate any changes.
2914 If at least one tag has a selection key, pressing `C-c C-c' will
2915 automatically present you with a special interface, listing inherited
2916 tags, the tags of the current headline, and a list of all legal tags
2917 with corresponding keys(2). In this interface, you can use the
2921 Pressing keys assigned to tags will add or remove them from the
2922 list of tags in the current line. Selecting a tag in a group of
2923 mutually exclusive tags will turn off any other tags from that
2927 Enter a tag in the minibuffer, even if the tag is not in the
2928 predefined list. You will be able to complete on all tags present
2932 Clear all tags for this line.
2935 Accept the modified set.
2938 Abort without installing changes.
2941 If `q' is not assigned to a tag, it aborts like `C-g'.
2944 Turn off groups of mutually exclusive tags. Use this to (as an
2945 exception) assign several tags from such a group.
2948 Toggle auto-exit after the next change (see below). If you are
2949 using expert mode, the first `C-c' will display the selection
2952 This method lets you assign tags to a headline with very few keys. With
2953 the above setup, you could clear the current tags and set `@HOME',
2954 `Laptop' and `PC' tags with just the following keys: `C-c C-c <SPC> h l
2955 p <RET>'. Switching from `@HOME' to `@WORK' would be done with `C-c
2956 C-c w <RET>' or alternatively with `C-c C-c C-c w'. Adding the
2957 non-predefined tag `Sarah' could be done with `C-c C-c <TAB> S a r a h
2960 If you find that most of the time, you need only a single keypress to
2961 modify your list of tags, set the variable
2962 `org-fast-tag-selection-single-key'. Then you no longer have to press
2963 <RET> to exit fast tag selection - it will immediately exit after the
2964 first change. If you then occasionally need more keys, press `C-c' to
2965 turn off auto-exit for the current tag selection process (in effect:
2966 start selection with `C-c C-c C-c' instead of `C-c C-c'). If you set
2967 the variable to the value `expert', the special window is not even
2968 shown for single-key tag selection, it comes up only when you press an
2971 ---------- Footnotes ----------
2973 (1) In `org-mode-alist' use `'(:startgroup)' and `'(:endgroup)',
2974 respectively. Several groups are allowed.
2976 (2) Keys will automatically be assigned to tags which have no
2980 File: org, Node: Tag searches, Prev: Setting tags, Up: Tags
2985 Once a tags system has been set up, it can be used to collect related
2986 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
3128 `M-x org-insert-property-drawer'
3129 Insert a property drawer into the current entry. The drawer will
3130 be inserted early in the entry, but after the lines with planning
3131 information like deadlines.
3134 With the cursor in a property drawer, this executes property
3138 Set a property in the current entry. Both the property and the
3139 value can be inserted using completion.
3142 Switch property at point to the next/previous allowed value.
3145 Remove a property from the current entry.
3148 Globally remove a property, from all entries in the current file.
3151 File: org, Node: Special properties, Next: Property searches, Prev: Property syntax, Up: Properties and columns
3153 7.2 Special Properties
3154 ======================
3156 Special properties provide alternative access method to Org-mode
3157 features discussed in the previous chapters, like the TODO state or the
3158 priority of an entry. This interface exists so that you can include
3159 these states into columns view (*note Column view::). The following
3160 property names are special and should not be used as keys in the
3163 TODO The TODO keyword of the entry.
3164 TAGS The tags defined directly in the headline.
3165 ALLTAGS All tags, including inherited ones.
3166 PRIORITY The priority of the entry, a string with a single letter.
3167 DEADLINE The deadline time string, without the angular brackets.
3168 SCHEDULED The scheduling time stamp, without the angular brackets.
3171 File: org, Node: Property searches, Next: Column view, Prev: Special properties, Up: Properties and columns
3173 7.3 Property searches
3174 =====================
3176 To create sparse trees and special lists with selection based on
3177 properties, the same commands are used as for tag searches (*note Tag
3178 searches::), and the same logic applies. For example, a search string
3180 +WORK-BOSS+PRIORITY="A"+coffee="unlimited"+with={Sarah\|Denny}
3182 finds entries tagged `:WORK:' but not `:BOSS:', which also have a
3183 priority value `A', a `:coffee:' property with the value `unlimited',
3184 and a `:with:' property that is matched by the regular expression
3188 File: org, Node: Column view, Next: Property API, Prev: Property searches, Up: Properties and columns
3193 A great way to view and edit properties in an outline tree is _column
3194 view_. In column view, each outline item is turned into a table row.
3195 Columns in this table provide access to properties of the entries.
3196 Org-mode implements columns by overlaying a tabular structure over the
3197 headline of each item. While the headlines have been turned into a
3198 table row, you can still change the visibility of the outline tree.
3199 For example, you get a compact table by switching to CONTENTS view
3200 (`S-<TAB> S-<TAB>', or simply `c' while column view is active), but you
3201 can still open, read, and edit the entry below each headline. Or, you
3202 can switch to column view after executing a sparse tree command and in
3203 this way get a table only for the selected items. Column view also
3204 works in agenda buffers (*note Agenda views::) where queries have
3205 collected selected items, possibly from a number of files.
3209 * Defining columns:: The COLUMNS format property
3210 * Using column view:: How to create and use column view
3213 File: org, Node: Defining columns, Next: Using column view, Prev: Column view, Up: Column view
3215 7.4.1 Defining Columns
3216 ----------------------
3218 Setting up a column view first requires defining the columns. This is
3219 done by defining a column format line.
3223 * Scope of column definitions:: Where defined, where valid?
3224 * Column attributes:: Appearance and content of a column
3227 File: org, Node: Scope of column definitions, Next: Column attributes, Prev: Defining columns, Up: Defining columns
3229 7.4.1.1 Scope of column definitions
3230 ...................................
3232 To define a column format for an entire file, use a line like
3234 #+COLUMNS: %25ITEM %TAGS %PRIORITY %TODO
3236 To specify a format that only applies to a specific tree, add a
3237 COLUMNS property to the top node of that tree, for example
3238 ** Top node for columns view
3240 :COLUMNS: %25ITEM %TAGS %PRIORITY %TODO
3243 If a `COLUMNS' property is present in an entry, it defines columns
3244 for the entry itself, and for the entire subtree below it. Since the
3245 column definition is part of the hierarchical structure of the document,
3246 you can define columns on level 1 that are general enough for all
3247 sublevels, and more specific columns further down, when you edit a
3248 deeper part of the tree.
3251 File: org, Node: Column attributes, Prev: Scope of column definitions, Up: Defining columns
3253 7.4.1.2 Column attributes
3254 .........................
3256 A column definition sets the attributes of a column. The general
3257 definition looks like this:
3259 %[width]property[(title)][{summary-type}]
3261 Except for the percent sign and the property name, all items are
3262 optional. The individual parts have the following meaning:
3264 width An integer specifying the width of the column in characters.
3265 If omitted, the width will be determined automatically.
3266 property The property that should be edited in this column.
3267 (title) The header text for the column. If omitted, the
3268 property name is used.
3269 {summary-type} The summary type. If specified, the column values for
3270 parent nodes are computed from the children.
3271 Supported summary types are:
3272 {+} Sum numbers in this column.
3273 {:} Sum times, HH:MM:SS, plain numbers are hours.
3274 {X} Checkbox status, [X] if all children are [X].
3276 Here is an example for a complete columns definition, along with allowed
3279 :COLUMNS: %20ITEM %9Approved(Approved?){X} %Owner %11Status %10Time_Spent{:}
3280 :Owner_ALL: Tammy Mark Karl Lisa Don
3281 :Status_ALL: "In progress" "Not started yet" "Finished" ""
3282 :Approved_ALL: "[ ]" "[X]"
3284 The first column, `%25ITEM', means the first 25 characters of the
3285 item itself, i.e. of the headline. You probably always should start the
3286 column definition with the ITEM specifier. The other specifiers create
3287 columns `Owner' with a list of names as allowed values, for `Status'
3288 with four different possible values, and for a checkbox field
3289 `Approved'. When no width is given after the `%' character, the column
3290 will be exactly as wide as it needs to be in order to fully display all
3291 values. The `Approved' column does have a modified title (`Approved?',
3292 with a question mark). Summaries will be created for the `Time_Spent'
3293 column by adding time duration expressions like HH:MM, and for the
3294 `Approved' column, by providing an `[X]' status if all children have
3298 File: org, Node: Using column view, Prev: Defining columns, Up: Column view
3300 7.4.2 Using Column View
3301 -----------------------
3303 Turning column view on and off
3304 ..............................
3307 Create the column view for the local environment. This command
3308 searches the hierarchy, up from point, for a `COLUMNS' property
3309 that defines a format. When one is found, the column view table
3310 is established for the entire tree, starting from the entry that
3311 contains the `COLUMNS' property. If none is found, the format is
3312 taken from the `#+COLUMNS' line or from the variable
3313 `org-columns-default-format', and column view is established for
3314 the current entry and its subtree.
3322 `<left> <right> <up> <down>'
3323 Move through the column view from field to field.
3326 Switch to the next/previous allowed value of the field. For this,
3327 you have to have specified allowed values for a property.
3330 Same as `S-<left>/<right>'
3333 Edit the property at point. For the special properties, this will
3334 invoke the same interface that you normally use to change that
3335 property. For example, when editing a TAGS property, the tag
3336 completion or fast selection interface will pop up.
3339 View the full value of this property. This is useful if the width
3340 of the column is smaller than that of the value.
3343 Edit the list of allowed values for this property. If the list is
3344 found in the hierarchy, the modified values is stored there. If
3345 no list is found, the new value is stored in the first entry that
3346 is part of the current column view.
3348 Modifying the table structure
3349 .............................
3352 Make the column narrower/wider by one character.
3355 Insert a new column, to the right of the current column.
3358 Delete the current column.
3361 File: org, Node: Property API, Prev: Column view, Up: Properties and columns
3363 7.5 The Property API
3364 ====================
3366 There is a full API for accessing and changing properties. This API can
3367 be used by Emacs Lisp programs to work with properties and to implement
3368 features based on them. For more information see *Note Using the
3372 File: org, Node: Timestamps, Next: Agenda views, Prev: Properties and columns, Up: Top
3377 Items can be labeled with timestamps to make them useful for project
3382 * Time stamps:: Assigning a time to a tree entry
3383 * Creating timestamps:: Commands which insert timestamps
3384 * Deadlines and scheduling:: Planning your work
3385 * Progress logging:: Documenting when what work was done.
3388 File: org, Node: Time stamps, Next: Creating timestamps, Prev: Timestamps, Up: Timestamps
3390 8.1 Time stamps, deadlines and scheduling
3391 =========================================
3393 A time stamp is a specification of a date (possibly with time or a range
3394 of times) in a special format, either `<2003-09-16 Tue>' or
3395 `<2003-09-16 Tue 09:39>' or `<2003-09-16 Tue 12:00-12:30>'(1). A time
3396 stamp can appear anywhere in the headline or body of an org-tree entry.
3397 Its presence causes entries to be shown on specific dates in the agenda
3398 (*note Weekly/Daily agenda::). We distinguish:
3401 A simple time stamp just assigns a date/time to an item. This is
3402 just like writing down an appointment in a paper agenda, or like
3403 writing down an event in a diary, when you want to take note of
3404 when something happened. In the timeline and agenda displays, the
3405 headline of an entry associated with a plain time stamp will be
3406 shown exactly on that date.
3408 * Meet Peter at the movies <2006-11-01 Wed 19:15>
3409 * Discussion on climate change <2006-11-02 Thu 20:00-22:00>
3411 TIME STAMP WITH REPEATER INTERVAL
3412 A time stamp may contain a _repeater interval_, indicating that it
3413 applies not only on the given date, but again and again after a
3414 certain interval of N days (d), weeks (w), months(m), or years(y).
3415 The following will show up in the agenda every Wednesday:
3417 * Pick up Sam at school <2007-05-16 Wed 12:30 +1w>
3419 DIARY-STYLE SEXP ENTRIES
3420 For more complex date specifications, Org-mode supports using the
3421 special sexp diary entries implemented in the Emacs calendar/diary
3422 package. For example
3424 * The nerd meeting on every 2nd Thursday of the month
3425 <%%(diary-float t 4 2)>
3428 Two time stamps connected by `--' denote a range. The headline
3429 will be shown on the first and last day of the range, and on any
3430 dates that are displayed and fall in the range. Here is an
3433 ** Meeting in Amsterdam
3434 <2004-08-23 Mon>--<2004-08-26 Thu>
3437 Just like a plain time stamp, but with square brackets instead of
3438 angular ones. These time stamps are inactive in the sense that
3439 they do _not_ trigger an entry to show up in the agenda.
3441 * Gillian comes late for the fifth time [2006-11-01 Wed]
3444 ---------- Footnotes ----------
3446 (1) This is the standard ISO date/time format. If you cannot get
3447 used to these, see *Note Custom time format::
3450 File: org, Node: Creating timestamps, Next: Deadlines and scheduling, Prev: Time stamps, Up: Timestamps
3452 8.2 Creating timestamps
3453 =======================
3455 For Org-mode to recognize time stamps, they need to be in the specific
3456 format. All commands listed below produce time stamps in the correct
3460 Prompt for a date and insert a corresponding time stamp. When the
3461 cursor is at a previously used time stamp, it is updated to NOW.
3462 When this command is used twice in succession, a time range is
3466 Like `C-c .', but use the alternative format which contains date
3467 and time. The default time can be rounded to multiples of 5
3468 minutes, see the option `org-time-stamp-rounding-minutes'.
3471 Like `C-c .', but insert an inactive time stamp that will not cause
3475 Insert a time stamp corresponding to the cursor date in the
3479 Access the Emacs calendar for the current date. If there is a
3480 timestamp in the current line, goto the corresponding date instead.
3483 Access the agenda for the date given by the time stamp or -range at
3484 point (*note Weekly/Daily agenda::).
3488 Change date at cursor by one day. These key bindings conflict with
3489 CUA-mode (*note Conflicts::).
3493 Change the item under the cursor in a timestamp. The cursor can
3494 be on a year, month, day, hour or minute. Note that if the cursor
3495 is in a headline and not at a time stamp, these same keys modify
3496 the priority of an item. (*note Priorities::). The key bindings
3497 also conflict with CUA-mode (*note Conflicts::).
3500 Evaluate a time range by computing the difference between start and
3501 end. With prefix arg, insert result after the time range (in a
3502 table: into the following column).
3506 * The date/time prompt:: How org-mode helps you entering date and time
3507 * Custom time format:: Making dates look differently
3510 File: org, Node: The date/time prompt, Next: Custom time format, Prev: Creating timestamps, Up: Creating timestamps
3512 8.2.1 The date/time prompt
3513 --------------------------
3515 When Org-mode prompts for a date/time, the prompt suggests to enter an
3516 ISO date. But it will in fact accept any string containing some date
3517 and/or time information. You can, for example, use `C-y' to paste a
3518 (possibly multi-line) string copied from an email message. Org-mode
3519 will find whatever information is in there and will replace anything not
3520 specified with the current date and time. For example:
3522 3-2-5 --> 2003-02-05
3523 feb 15 --> currentyear-02-15
3524 sep 12 9 --> 2009-09-12
3525 12:45 --> today 12:45
3526 22 sept 0:34 --> currentyear-09-22 0:34
3527 12 --> currentyear-currentmonth-12
3528 Fri --> nearest Friday (today or later)
3529 +4 --> 4 days from now (if +N is the only thing given)
3531 The function understands English month and weekday abbreviations. If
3532 you want to use unabbreviated names and/or other languages, configure
3533 the variables `parse-time-months' and `parse-time-weekdays'.
3535 Parallel to the minibuffer prompt, a calendar is popped up(1). When
3536 you exit the date prompt, either by clicking on a date in the calendar,
3537 or by pressing <RET>, the date selected in the calendar will be
3538 combined with the information entered at the prompt. You can control
3539 the calendar fully from the minibuffer:
3542 Scroll calendar backwards by one month.
3545 Scroll calendar forwards by one month.
3548 Select date by clicking on it.
3569 Choose date in calendar (only if nothing was typed into
3572 ---------- Footnotes ----------
3574 (1) If you don't need/want the calendar, configure the variable
3575 `org-popup-calendar-for-date-prompt'.
3578 File: org, Node: Custom time format, Prev: The date/time prompt, Up: Creating timestamps
3580 8.2.2 Custom time format
3581 ------------------------
3583 Org-mode uses the standard ISO notation for dates and times as it is
3584 defined in ISO 8601. If you cannot get used to this and require another
3585 representation of date and time to keep you happy, you can get it by
3586 customizing the variables `org-display-custom-times' and
3587 `org-time-stamp-custom-formats'.
3590 Toggle the display of custom formats for dates and times.
3592 Org-mode needs the default format for scanning, so the custom date/time
3593 format does not _replace_ the default format - instead it is put _over_
3594 the default format using text properties. This has the following
3596 * You cannot place the cursor onto a time stamp anymore, only before
3599 * The `S-<up>/<down>' keys can no longer be used to adjust each
3600 component of a time stamp. If the cursor is at the beginning of
3601 the stamp, `S-<up>/<down>' will change the stamp by one day, just
3602 like `S-<left>/<right>'. At the end of the stamp, the time will
3603 be changed by one minute.
3605 * If the time stamp contains a range of clock times or a repeater,
3606 these will not be overlayed, but remain in the buffer as they were.
3608 * When you delete a time stamp character-by-character, it will only
3609 disappear from the buffer after _all_ (invisible) characters
3610 belonging to the ISO timestamp have been removed.
3612 * If the custom time stamp format is longer than the default and you
3613 are using dates in tables, table alignment will be messed up. If
3614 the custom format is shorter, things do work as expected.
3617 File: org, Node: Deadlines and scheduling, Next: Progress logging, Prev: Creating timestamps, Up: Timestamps
3619 8.3 Deadlines and Scheduling
3620 ============================
3622 A time stamp may be preceded by special keywords to facilitate planning
3626 The task (most likely a TODO item) is supposed to be finished on
3627 that date, and it will be listed then. In addition, the
3628 compilation for _today_ will carry a warning about the approaching
3629 or missed deadline, starting `org-deadline-warning-days' before
3630 the due date, and continuing until the entry is marked DONE. An
3633 *** TODO write article about the Earth for the Guide
3634 The editor in charge is [[bbdb:Ford Prefect]]
3635 DEADLINE: <2004-02-29 Sun>
3637 You can specify a different lead time for warnings for a specific
3638 deadlines using the following syntax. Here is an example with a
3639 warning period of 5 days `DEADLINE: <2004-02-29 Sun -5d>'.
3642 You are planning to start working on that task on the given date.
3643 The headline will be listed under the given date(1). In addition,
3644 a reminder that the scheduled date has passed will be present in
3645 the compilation for _today_, until the entry is marked DONE.
3646 I.e., the task will automatically be forwarded until completed.
3648 *** TODO Call Trillian for a date on New Years Eve.
3649 SCHEDULED: <2004-12-25 Sat>
3653 * Inserting deadline/schedule:: Planning items
3654 * Repeated tasks:: Items that show up again and again
3656 ---------- Footnotes ----------
3658 (1) It will still be listed on that date after it has been marked
3659 DONE. If you don't like this, set the variable
3660 `org-agenda-skip-scheduled-if-done'.
3663 File: org, Node: Inserting deadline/schedule, Next: Repeated tasks, Prev: Deadlines and scheduling, Up: Deadlines and scheduling
3665 8.3.1 Inserting deadline/schedule
3666 ---------------------------------
3668 The following commands allow to quickly insert a deadline or to schedule
3672 Insert `DEADLINE' keyword along with a stamp. The insertion will
3673 happen in the line directly following the headline.
3676 Create a sparse tree with all deadlines that are either past-due,
3677 or which will become due within `org-deadline-warning-days'. With
3678 `C-u' prefix, show all deadlines in the file. With a numeric
3679 prefix, check that many days. For example, `C-1 C-c C-w' shows
3680 all deadlines due tomorrow.
3683 Insert `SCHEDULED' keyword along with a stamp. The insertion will
3684 happen in the line directly following the headline. Any CLOSED
3685 timestamp will be removed.
3688 File: org, Node: Repeated tasks, Prev: Inserting deadline/schedule, Up: Deadlines and scheduling
3690 8.3.2 Repeated Tasks
3691 --------------------
3693 Some tasks need to be repeated again and again, and Org-mode therefore
3694 allows to use a repeater in a DEADLINE or SCHEDULED time stamp, for
3696 ** TODO Pay the rent
3697 DEADLINE: <2005-10-01 Sat +1m>
3699 Deadlines and scheduled items produce entries in the agenda when they
3700 are over-due, so it is important to be able to mark such an entry as
3701 completed once you have done so. When you mark a DEADLINE or a SCHEDULE
3702 with the todo keyword DONE, it will no longer produce entries in the
3703 agenda. The problem with this is, however, that then also the _next_
3704 instance of the repeated entry will not be active. Org-mode deals with
3705 this in the following way: When you try to mark such an entry DONE
3706 (using `C-c C-t'), it will shift the base date of the repeating time
3707 stamp by the repeater interval, and immediately set the entry state
3708 back to TODO. In the example above, setting the state to DONE would
3709 actually switch the date like this:
3711 ** TODO Pay the rent
3712 DEADLINE: <2005-11-01 Tue +1m>
3714 You will also be prompted for a note that will be put under the
3715 DEADLINE line to keep a record that you actually acted on the previous
3716 instance of this deadline.
3718 As a consequence of shifting the base date, this entry will no
3719 longer be visible in the agenda when checking past dates, but all
3720 future instances will be visible.
3722 You may have both scheduling and deadline information for a specific
3723 task - just make sure that the repeater intervals on both are the same.
3726 File: org, Node: Progress logging, Prev: Deadlines and scheduling, Up: Timestamps
3728 8.4 Progress Logging
3729 ====================
3731 Org-mode can automatically record a time stamp when you mark a TODO item
3732 as DONE, or even each time when you change the state of a TODO item.
3733 You can also measure precisely the time you spent on specific items in a
3734 project by starting and stopping a clock when you start and stop working
3735 on an aspect of a project.
3739 * Closing items:: When was this entry marked DONE?
3740 * Tracking TODO state changes:: When did the status change?
3741 * Clocking work time:: When exactly did you work on this item?
3744 File: org, Node: Closing items, Next: Tracking TODO state changes, Prev: Progress logging, Up: Progress logging
3749 If you want to keep track of _when_ a certain TODO item was finished,
3750 turn on logging with(1)
3752 (setq org-log-done t)
3754 Then each time you turn a TODO entry into DONE using either `C-c C-t'
3755 in the Org-mode buffer or `t' in the agenda buffer, a line `CLOSED:
3756 [timestamp]' will be inserted just after the headline. If you turn the
3757 entry back into a TODO item through further state cycling, that line
3758 will be removed again. In the timeline (*note Timeline::) and in the
3759 agenda (*note Weekly/Daily agenda::), you can then use the `l' key to
3760 display the TODO items closed on each day, giving you an overview of
3761 what has been done on a day. If you want to record a note along with
3762 the timestamp, use(2)
3764 (setq org-log-done '(done))
3766 ---------- Footnotes ----------
3768 (1) The corresponding in-buffer setting is: `#+STARTUP: logdone'
3770 (2) The corresponding in-buffer setting is: `#+STARTUP: lognotedone'
3773 File: org, Node: Tracking TODO state changes, Next: Clocking work time, Prev: Closing items, Up: Progress logging
3775 8.4.2 Tracking TODO state changes
3776 ---------------------------------
3778 When TODO keywords are used as workflow states (*note Workflow
3779 states::), you might want to keep track of when a state change occurred,
3780 and you may even want to attach notes to that state change. With the
3783 (setq org-log-done '(state))
3785 each state change will prompt you for a note that will be attached to
3786 the current headline. Very likely you do not want this verbose tracking
3787 all the time, so it is probably better to configure this behavior with
3788 in-buffer options. For example, if you are tracking purchases, put
3789 these into a separate file that starts with:
3791 #+SEQ_TODO: TODO ORDERED INVOICE PAYED RECEIVED SENT
3792 #+STARTUP: lognotestate
3795 File: org, Node: Clocking work time, Prev: Tracking TODO state changes, Up: Progress logging
3797 8.4.3 Clocking work time
3798 ------------------------
3800 Org-mode allows you to clock the time you spent on specific tasks in a
3801 project. When you start working on an item, you can start the clock.
3802 When you stop working on that task, or when you mark the task done, the
3803 clock is stopped and the corresponding time interval is recorded. It
3804 also computes the total time spent on each subtree of a project.
3807 Start the clock on the current item (clock-in). This inserts the
3808 CLOCK keyword together with a timestamp.
3811 Stop the clock (clock-out). The inserts another timestamp at the
3812 same location where the clock was last started. It also directly
3813 computes the resulting time in inserts it after the time range as
3814 `=> HH:MM'. See the variable `org-log-done' for the possibility to
3815 record an additional note together with the clock-out time
3819 Recompute the time interval after changing one of the time stamps.
3820 This is only necessary if you edit the time stamps directly. If
3821 you change them with `S-<cursor>' keys, the update is automatic.
3824 Changing the TODO state of an item to DONE automatically stops the
3825 clock if it is running in this same item.
3828 Cancel the current clock. This is useful if a clock was started by
3829 mistake, or if you ended up working on something else.
3832 Display time summaries for each subtree in the current buffer.
3833 This puts overlays at the end of each headline, showing the total
3834 time recorded under that heading, including the time of any
3835 subheadings. You can use visibility cycling to study the tree, but
3836 the overlays disappear when you change the buffer (see variable
3837 `org-remove-highlights-with-change') or press `C-c C-c'.
3840 Insert a dynamic block (*note Dynamic blocks::) containing a clock
3841 report as an org-mode table into the current file.
3842 #+BEGIN: clocktable :maxlevel 2 :emphasize nil
3845 If such a block already exists, its content is replaced by the new
3846 table. The `BEGIN' line can specify options:
3847 :maxlevels Maximum level depth to which times are listed in the table.
3848 :emphasize When `t', emphasize level one and level two items
3849 :block The time block to consider. This block is specified relative
3850 to the current time and may be any of these keywords:
3851 `today', `yesterday', `thisweek', `lastweek',
3852 `thismonth', `lastmonth', `thisyear', or `lastyear'.
3853 :tstart A time string specifying when to start considering times
3854 :tend A time string specifying when to stop considering times
3855 So to get a clock summary for the current day, you could write
3856 #+BEGIN: clocktable :maxlevel 2 :block today
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>"
3866 Update all dynamic blocks (*note Dynamic blocks::). This is
3867 useful if you have several clocktable blocks in a buffer.
3869 The `l' key may be used in the timeline (*note Timeline::) and in
3870 the agenda (*note Weekly/Daily agenda::) to show which tasks have been
3871 worked on or closed during a day.
3873 ---------- Footnotes ----------
3875 (1) The corresponding in-buffer setting is: `#+STARTUP:
3878 (2) Note that all parameters must be specified in a single line -
3879 the line is broken here only to fit it onto the manual.
3882 File: org, Node: Agenda views, Next: Embedded LaTeX, Prev: Timestamps, Up: Top
3887 Due to the way Org-mode works, TODO items, time-stamped items, and
3888 tagged headlines can be scattered throughout a file or even a number of
3889 files. To get an overview over open action items, or over events that
3890 are important for a particular date, this information must be collected,
3891 sorted and displayed in an organized way.
3893 Org-mode can select items based on various criteria, and display them
3894 in a separate buffer. Six different view types are provided:
3896 * an _agenda_ that is like a calendar and shows information for
3899 * a _TODO list_ that covers all unfinished action items,
3901 * a _tags view_, showings headlines based on the tags associated
3904 * a _timeline view_ that shows all events in a single Org-mode file,
3905 in time-sorted view,
3907 * a _stuck projects view_ showing projects that currently don't move
3910 * _custom views_ that are special tag/keyword searches and
3911 combinations of different views.
3913 The extracted information is displayed in a special _agenda buffer_.
3914 This buffer is read-only, but provides commands to visit the
3915 corresponding locations in the original Org-mode files, and even to
3916 edit these files remotely.
3918 Two variables control how the agenda buffer is displayed and whether
3919 the window configuration is restored when the agenda exits:
3920 `org-agenda-window-setup' and `org-agenda-restore-windows-after-quit'.
3924 * Agenda files:: Files being searched for agenda information
3925 * Agenda dispatcher:: Keyboard access to agenda views
3926 * Built-in agenda views:: What is available out of the box?
3927 * Presentation and sorting:: How agenda items are prepared for display
3928 * Agenda commands:: Remote editing of org trees
3929 * Custom agenda views:: Defining special searches and views
3932 File: org, Node: Agenda files, Next: Agenda dispatcher, Prev: Agenda views, Up: Agenda views
3937 The information to be shown is collected from all _agenda files_, the
3938 files listed in the variable `org-agenda-files'(1). Thus even if you
3939 only work with a single Org-mode file, this file should be put into
3940 that list(2). You can customize `org-agenda-files', but the easiest
3941 way to maintain it is through the following commands
3944 Add current file to the list of agenda files. The file is added to
3945 the front of the list. If it was already in the list, it is moved
3946 to the front. With prefix arg, file is added/moved to the end.
3949 Remove current file from the list of agenda files.
3953 Cycle through agenda file list, visiting one file after the other.
3955 The Org menu contains the current list of files and can be used to
3958 ---------- Footnotes ----------
3960 (1) If the value of that variable is not a list, but a single file
3961 name, then the list of agenda files will be maintained in that external
3964 (2) When using the dispatcher, pressing `1' before selecting a
3965 command will actually limit the command to the current file, and ignore
3966 `org-agenda-files' until the next dispatcher command.
3969 File: org, Node: Agenda dispatcher, Next: Built-in agenda views, Prev: Agenda files, Up: Agenda views
3971 9.2 The agenda dispatcher
3972 =========================
3974 The views are created through a dispatcher that should be bound to a
3975 global key, for example `C-c a' (*note Installation::). In the
3976 following we will assume that `C-c a' is indeed how the dispatcher is
3977 accessed and list keyboard access to commands accordingly. After
3978 pressing `C-c a', an additional letter is required to execute a
3979 command. The dispatcher offers the following default commands:
3981 Create the calendar-like agenda (*note Weekly/Daily agenda::).
3984 Create a list of all TODO items (*note Global TODO list::).
3987 Create a list of headlines matching a TAGS expression (*note
3988 Matching tags and properties::).
3991 Create the timeline view for the current buffer (*note Timeline::).
3994 Create a list of stuck projects (*note Stuck projects::).
3997 Restrict an agenda command to the current buffer. After pressing
3998 `1', you still need to press the character selecting the command.
4001 If there is an active region, restrict the following agenda
4002 command to the region. Otherwise, restrict it to the current
4003 subtree. After pressing `0', you still need to press the
4004 character selecting the command.
4006 You can also define custom commands that will be accessible through
4007 the dispatcher, just like the default commands. This includes the
4008 possibility to create extended agenda buffers that contain several
4009 blocks together, for example the weekly agenda, the global TODO list and
4010 a number of special tags matches. *Note Custom agenda views::.
4013 File: org, Node: Built-in agenda views, Next: Presentation and sorting, Prev: Agenda dispatcher, Up: Agenda views
4015 9.3 The built-in agenda views
4016 =============================
4018 In this section we describe the built-in views.
4022 * Weekly/Daily agenda:: The calendar page with current tasks
4023 * Global TODO list:: All unfinished action items
4024 * Matching tags and properties:: Structured information with fine-tuned search
4025 * Timeline:: Time-sorted view for single file
4026 * Stuck projects:: Find projects you need to review
4029 File: org, Node: Weekly/Daily agenda, Next: Global TODO list, Prev: Built-in agenda views, Up: Built-in agenda views
4031 9.3.1 The weekly/daily agenda
4032 -----------------------------
4034 The purpose of the weekly/daily _agenda_ is to act like a page of a
4035 paper agenda, showing all the tasks for the current week or day.
4038 Compile an agenda for the current week from a list of org files.
4039 The agenda shows the entries for each day. With a `C-u' prefix (or
4040 when the variable `org-agenda-include-all-todo' is `t'), all
4041 unfinished TODO items (including those without a date) are also
4042 listed at the beginning of the buffer, before the first date.
4044 Remote editing from the agenda buffer means, for example, that you
4045 can change the dates of deadlines and appointments from the agenda
4046 buffer. The commands available in the Agenda buffer are listed in
4047 *Note Agenda commands::.
4049 Calendar/Diary integration
4050 ..........................
4052 Emacs contains the calendar and diary by Edward M. Reingold. The
4053 calendar displays a three-month calendar with holidays from different
4054 countries and cultures. The diary allows you to keep track of
4055 anniversaries, lunar phases, sunrise/set, recurrent appointments
4056 (weekly, monthly) and more. In this way, it is quite complementary to
4057 Org-mode. It can be very useful to combine output from Org-mode with
4060 In order to include entries from the Emacs diary into Org-mode's
4061 agenda, you only need to customize the variable
4063 (setq org-agenda-include-diary t)
4065 After that, everything will happen automatically. All diary entries
4066 including holidays, anniversaries etc will be included in the agenda
4067 buffer created by Org-mode. <SPC>, <TAB>, and <RET> can be used from
4068 the agenda buffer to jump to the diary file in order to edit existing
4069 diary entries. The `i' command to insert new entries for the current
4070 date works in the agenda buffer, as well as the commands `S', `M', and
4071 `C' to display Sunrise/Sunset times, show lunar phases and to convert
4072 to other calendars, respectively. `c' can be used to switch back and
4073 forth between calendar and agenda.
4075 If you are using the diary only for sexp entries and holidays, it is
4076 faster to not use the above setting, but instead to copy or even move
4077 the entries into an Org-mode file. Org-mode evaluates diary-style sexp
4078 entries, and does it faster because there is no overhead for first
4079 creating the diary display. Note that the sexp entries must start at
4080 the left margin, no white space is allowed before them. For example,
4081 the following segment of an Org-mode file will be processed and entries
4082 will be made in the agenda:
4084 * Birthdays and similar stuff
4086 %%(org-calendar-holiday) ; special function for holiday names
4088 %%(diary-anniversary 14 5 1956) Arthur Dent is %d years old
4089 %%(diary-anniversary 2 10 1869) Mahatma Gandhi would be %d years old
4092 File: org, Node: Global TODO list, Next: Matching tags and properties, Prev: Weekly/Daily agenda, Up: Built-in agenda views
4094 9.3.2 The global TODO list
4095 --------------------------
4097 The global TODO list contains all unfinished TODO items, formatted and
4098 collected into a single place.
4101 Show the global TODO list. This collects the TODO items from all
4102 agenda files (*note Agenda views::) into a single buffer. The
4103 buffer is in `agenda-mode', so there are commands to examine and
4104 manipulate the TODO entries directly from that buffer (*note
4108 Like the above, but allows selection of a specific TODO keyword.
4109 You can also do this by specifying a prefix argument to `C-c a t'.
4110 With a `C-u' prefix you are prompted for a keyword, and you may
4111 also specify several keywords by separating them with `|' as
4112 boolean OR operator. With a numeric prefix, the Nth keyword in
4113 `org-todo-keywords' is selected. The `r' key in the agenda buffer
4114 regenerates it, and you can give a prefix argument to this command
4115 to change the selected TODO keyword, for example `3 r'. If you
4116 often need a search for a specific keyword, define a custom
4117 command for it (*note Agenda dispatcher::).
4118 Matching specific TODO keywords can also be done as part of a tags
4119 search (*note Tag searches::).
4121 Remote editing of TODO items means that you can change the state of a
4122 TODO entry with a single key press. The commands available in the TODO
4123 list are described in *Note Agenda commands::.
4125 Normally the global todo list simply shows all headlines with TODO
4126 keywords. This list can become very long. There are two ways to keep
4128 - Some people view a TODO item that has been _scheduled_ for
4129 execution (*note Time stamps::) as no longer _open_. Configure the
4130 variable `org-agenda-todo-ignore-scheduled' to exclude scheduled
4131 items from the global TODO list.
4133 - TODO items may have sublevels to break up the task into subtasks.
4134 In such cases it may be enough to list only the highest level TODO
4135 headline and omit the sublevels from the global list. Configure
4136 the variable `org-agenda-todo-list-sublevels' to get this behavior.
4139 File: org, Node: Matching tags and properties, Next: Timeline, Prev: Global TODO list, Up: Built-in agenda views
4141 9.3.3 Matching Tags and Properties
4142 ----------------------------------
4144 If headlines in the agenda files are marked with _tags_ (*note Tags::),
4145 you can select headlines based on the tags that apply to them and
4146 collect them into an agenda buffer.
4149 Produce a list of all headlines that match a given set of tags.
4150 The command prompts for a selection criterion, which is a boolean
4151 logic expression with tags, like `+WORK+URGENT-WITHBOSS' or
4152 `WORK|HOME' (*note Tags::). If you often need a specific search,
4153 define a custom command for it (*note Agenda dispatcher::).
4156 Like `C-c a m', but only select headlines that are also TODO items
4157 and force checking subitems (see variable
4158 `org-tags-match-list-sublevels'). Matching specific todo keywords
4159 together with a tags match is also possible, see *Note Tag
4162 The commands available in the tags list are described in *Note
4166 File: org, Node: Timeline, Next: Stuck projects, Prev: Matching tags and properties, Up: Built-in agenda views
4168 9.3.4 Timeline for a single file
4169 --------------------------------
4171 The timeline summarizes all time-stamped items from a single Org-mode
4172 file in a _time-sorted view_. The main purpose of this command is to
4173 give an overview over events in a project.
4176 Show a time-sorted view of the org file, with all time-stamped
4177 items. When called with a `C-u' prefix, all unfinished TODO
4178 entries (scheduled or not) are also listed under the current date.
4180 The commands available in the timeline buffer are listed in *Note
4184 File: org, Node: Stuck projects, Prev: Timeline, Up: Built-in agenda views
4186 9.3.5 Stuck projects
4187 --------------------
4189 If you are following a system like David Allen's GTD to organize your
4190 work, one of the "duties" you have is a regular review to make sure
4191 that all projects move along. A _stuck_ project is a project that has
4192 no defined next actions, so it will never show up in the TODO lists
4193 Org-mode produces. During the review, you need to identify such
4194 projects and define next actions for them.
4197 List projects that are stuck.
4200 Customize the variable `org-stuck-projects' to define what a stuck
4201 project is and how to find it.
4203 You almost certainly will have to configure this view before it will
4204 work for you. The built-in default assumes that all your projects are
4205 level-2 headlines, and that a project is not stuck if it has at least
4206 one entry marked with a todo keyword TODO or NEXT or NEXTACTION.
4208 Lets assume that you, in your own way of using Org-mode, identify
4209 projects with a tag PROJECT, and that you use a todo keyword MAYBE to
4210 indicate a project that should not be considered yet. Lets further
4211 assume that the todo keyword DONE marks finished projects, and that NEXT
4212 and TODO indicate next actions. The tag @SHOP indicates shopping and
4213 is a next action even without the NEXT tag. Finally, if the project
4214 contains the special word IGNORE anywhere, it should not be listed
4215 either. In this case you would start by identifying eligible projects
4216 with a tags/todo match `+PROJECT/-MAYBE-DONE', and then check for TODO,
4217 NEXT, @SHOP, and IGNORE in the subtree to identify projects that are
4218 not stuck. The correct customization for this is
4220 (setq org-stuck-projects
4221 '("+PROJECT/-MAYBE-DONE" ("NEXT" "TODO") ("@SHOP")
4225 File: org, Node: Presentation and sorting, Next: Agenda commands, Prev: Built-in agenda views, Up: Agenda views
4227 9.4 Presentation and sorting
4228 ============================
4230 Before displaying items in an agenda view, Org-mode visually prepares
4231 the items and sorts them. Each item occupies a single line. The line
4232 starts with a _prefix_ that contains the _category_ (*note
4233 Categories::) of the item and other important information. You can
4234 customize the prefix using the option `org-agenda-prefix-format'. The
4235 prefix is followed by a cleaned-up version of the outline headline
4236 associated with the item.
4240 * Categories:: Not all tasks are equal
4241 * Time-of-day specifications:: How the agenda knows the time
4242 * Sorting of agenda items:: The order of things
4245 File: org, Node: Categories, Next: Time-of-day specifications, Prev: Presentation and sorting, Up: Presentation and sorting
4250 The category is a broad label assigned to each agenda item. By default,
4251 the category is simply derived from the file name, but you can also
4252 specify it with a special line in the buffer, like this:
4256 If there are several such lines in a file, each specifies the
4257 category for the text below it (but the first category also applies to
4258 any text before the first CATEGORY line). The display in the agenda
4259 buffer looks best if the category is not longer than 10 characters.
4262 File: org, Node: Time-of-day specifications, Next: Sorting of agenda items, Prev: Categories, Up: Presentation and sorting
4264 9.4.2 Time-of-Day Specifications
4265 --------------------------------
4267 Org-mode checks each agenda item for a time-of-day specification. The
4268 time can be part of the time stamp that triggered inclusion into the
4269 agenda, for example as in `<2005-05-10 Tue 19:00>'. Time ranges can be
4270 specified with two time stamps, like
4271 `<2005-05-10 Tue 20:30>--<2005-05-10 Tue 22:15>'.
4273 In the headline of the entry itself, a time(range) may also appear as
4274 plain text (like `12:45' or a `8:30-1pm'. If the agenda integrates the
4275 Emacs diary (*note Weekly/Daily agenda::), time specifications in diary
4276 entries are recognized as well.
4278 For agenda display, Org-mode extracts the time and displays it in a
4279 standard 24 hour format as part of the prefix. The example times in
4280 the previous paragraphs would end up in the agenda like this:
4282 8:30-13:00 Arthur Dent lies in front of the bulldozer
4283 12:45...... Ford Prefect arrives and takes Arthur to the pub
4284 19:00...... The Vogon reads his poem
4285 20:30-22:15 Marwin escorts the Hitchhikers to the bridge
4287 If the agenda is in single-day mode, or for the display of today, the
4288 timed entries are embedded in a time grid, like
4290 8:00...... ------------------
4291 8:30-13:00 Arthur Dent lies in front of the bulldozer
4292 10:00...... ------------------
4293 12:00...... ------------------
4294 12:45...... Ford Prefect arrives and takes Arthur to the pub
4295 14:00...... ------------------
4296 16:00...... ------------------
4297 18:00...... ------------------
4298 19:00...... The Vogon reads his poem
4299 20:00...... ------------------
4300 20:30-22:15 Marwin escorts the Hitchhikers to the bridge
4302 The time grid can be turned on and off with the variable
4303 `org-agenda-use-time-grid', and can be configured with
4304 `org-agenda-time-grid'.
4307 File: org, Node: Sorting of agenda items, Prev: Time-of-day specifications, Up: Presentation and sorting
4309 9.4.3 Sorting of agenda items
4310 -----------------------------
4312 Before being inserted into a view, the items are sorted. How this is
4313 done depends on the type of view.
4314 * For the daily/weekly agenda, the items for each day are sorted.
4315 The default order is to first collect all items containing an
4316 explicit time-of-day specification. These entries will be shown
4317 at the beginning of the list, as a _schedule_ for the day. After
4318 that, items remain grouped in categories, in the sequence given by
4319 `org-agenda-files'. Within each category, items are sorted by
4320 priority (*note Priorities::), which is composed of the base
4321 priority (2000 for priority `A', 1000 for `B', and 0 for `C'),
4322 plus additional increments for overdue scheduled or deadline items.
4324 * For the TODO list, items remain in the order of categories, but
4325 within each category, sorting takes place according to priority
4326 (*note Priorities::).
4328 * For tags matches, items are not sorted at all, but just appear in
4329 the sequence in which they are found in the agenda files.
4331 Sorting can be customized using the variable
4332 `org-agenda-sorting-strategy'.
4335 File: org, Node: Agenda commands, Next: Custom agenda views, Prev: Presentation and sorting, Up: Agenda views
4337 9.5 Commands in the agenda buffer
4338 =================================
4340 Entries in the agenda buffer are linked back to the org file or diary
4341 file where they originate. You are not allowed to edit the agenda
4342 buffer itself, but commands are provided to show and jump to the
4343 original entry location, and to edit the org-files "remotely" from the
4344 agenda buffer. In this way, all information is stored only once,
4345 removing the risk that your agenda and note files may diverge.
4347 Some commands can be executed with mouse clicks on agenda lines. For
4348 the other commands, the cursor needs to be in the desired line.
4354 Next line (same as <up>).
4357 Previous line (same as <down>).
4364 Display the original location of the item in another window.
4367 Display original location and recenter that window.
4372 Go to the original location of the item in another window. Under
4373 Emacs 22, `mouse-1' will also works for this.
4376 Go to the original location of the item and delete other windows.
4379 Toggle Follow mode. In Follow mode, as you move the cursor through
4380 the agenda buffer, the other window always shows the corresponding
4381 location in the org file. The initial setting for this mode in new
4382 agenda buffers can be set with the variable
4383 `org-agenda-start-with-follow-mode'.
4386 Display the entire subtree of the current item in an indirect
4387 buffer. With numerical prefix ARG, go up to this level and then
4388 take that tree. If ARG is negative, go up that many levels. With
4389 `C-u' prefix, do not remove the previously used indirect buffer.
4392 Toggle Logbook mode. In Logbook mode, entries that where marked
4393 DONE while logging was on (variable `org-log-done') are shown in
4394 the agenda, as are entries that have been clocked on that day.
4400 Delete other windows.
4403 Switch to day/week/month/year view. When switching to day or week
4404 view, this setting becomes the default for subseqent agenda
4405 commands. Since month and year views are slow to create, the do
4406 not become the default.
4409 Toggle the inclusion of diary entries. See *Note Weekly/Daily
4413 Toggle the time grid on and off. See also the variables
4414 `org-agenda-use-time-grid' and `org-agenda-time-grid'.
4417 Recreate the agenda buffer, for example to reflect the changes
4418 after modification of the time stamps of items with S-<left> and
4419 S-<right>. When the buffer is the global todo list, a prefix
4420 argument is interpreted to create a selective list for a specific
4424 Save all Org-mode buffers in the current Emacs session.
4427 Display the following `org-agenda-ndays' days. For example, if
4428 the display covers a week, switch to the following week. With
4429 prefix arg, go forward that many times `org-agenda-ndays' days.
4432 Display the previous dates.
4444 Undo a change due to a remote editing command. The change is
4445 undone both in the agenda buffer and in the remote buffer.
4448 Change the TODO state of the item, both in the agenda and in the
4452 Delete the current agenda item along with the entire subtree
4453 belonging to it in the original Org-mode file. If the text to be
4454 deleted remotely is longer than one line, the kill needs to be
4455 confirmed by the user. See variable `org-agenda-confirm-kill'.
4458 Archive the subtree corresponding to the current headline.
4461 Show all tags associated with the current item. Because of
4462 inheritance, this may be more than the tags listed in the line
4466 Set tags for the current headline.
4469 Toggle the ARCHIVE tag for the current headline.
4472 Set the priority for the current item. Org-mode prompts for the
4473 priority character. If you reply with <SPC>, the priority cookie
4474 is removed from the entry.
4477 Display weighted priority of current item.
4481 Increase the priority of the current item. The priority is
4482 changed in the original buffer, but the agenda is not resorted.
4483 Use the `r' key for this.
4487 Decrease the priority of the current item.
4493 Set a deadline for this item.
4496 Change the time stamp associated with the current line by one day
4497 into the future. With prefix argument, change it by that many
4498 days. For example, `3 6 5 S-<right>' will change it by a year.
4499 The stamp is changed in the original org file, but the change is
4500 not directly reflected in the agenda buffer. Use the `r' key to
4504 Change the time stamp associated with the current line by one day
4508 Change the time stamp associated with the current line to today.
4509 The key `>' has been chosen, because it is the same as `S-.' on my
4513 Start the clock on the current item. If a clock is running
4514 already, it is stopped first.
4517 Stop the previously started clock.
4520 Cancel the currently running clock.
4526 Open the Emacs calendar and move to the date at the agenda cursor.
4529 When in the calendar, compute and show the Org-mode agenda for the
4533 Insert a new entry into the diary. Prompts for the type of entry
4534 (day, weekly, monthly, yearly, anniversary, cyclic) and creates a
4535 new entry in the diary, just as `i d' etc. would do in the
4536 calendar. The date is taken from the cursor position.
4539 Show the phases of the moon for the three months around current
4543 Show sunrise and sunset times. The geographical location must be
4544 set with calendar variables, see documentation of the Emacs
4548 Convert the date at cursor into many other cultural and historic
4552 Show holidays for three month around the cursor date.
4555 Export a single iCalendar file containing entries from all agenda
4562 Write the agenda view to a file. Depending on the extension of the
4563 selected file name, the view will be exported as HTML (extension
4564 `.html' or `.htm'), Postscript (extension `.ps'), or plain text
4565 (any other extension). Use the variable
4566 `org-agenda-exporter-settings' to set options for `ps-print' and
4567 for `htmlize' to be used during export.
4573 Quit agenda, remove the agenda buffer.
4576 Exit agenda, remove the agenda buffer and all buffers loaded by
4577 Emacs for the compilation of the agenda. Buffers created by the
4578 user to visit org files will not be removed.
4581 File: org, Node: Custom agenda views, Prev: Agenda commands, Up: Agenda views
4583 9.6 Custom agenda views
4584 =======================
4586 Custom agenda commands serve two purposes: to store and quickly access
4587 frequently used TODO and tags searches, and to create special composite
4588 agenda buffers. Custom agenda commands will be accessible through the
4589 dispatcher (*note Agenda dispatcher::), just like the default commands.
4593 * Storing searches:: Type once, use often
4594 * Block agenda:: All the stuff you need in a single buffer
4595 * Setting Options:: Changing the rules
4596 * Exporting Agenda Views:: Writing agendas to files.
4597 * Extracting Agenda Information for other programs::
4600 File: org, Node: Storing searches, Next: Block agenda, Prev: Custom agenda views, Up: Custom agenda views
4602 9.6.1 Storing searches
4603 ----------------------
4605 The first application of custom searches is the definition of keyboard
4606 shortcuts for frequently used searches, either creating an agenda
4607 buffer, or a sparse tree (the latter covering of course only the current
4608 buffer). Custom commands are configured in the variable
4609 `org-agenda-custom-commands'. You can customize this variable, for
4610 example by pressing `C-c a C'. You can also directly set it with Emacs
4611 Lisp in `.emacs'. The following example contains all valid search
4614 (setq org-agenda-custom-commands
4615 '(("w" todo "WAITING")
4616 ("W" todo-tree "WAITING")
4617 ("u" tags "+BOSS-URGENT")
4618 ("v" tags-todo "+BOSS-URGENT")
4619 ("U" tags-tree "+BOSS-URGENT")
4620 ("f" occur-tree "\\<FIXME\\>")))
4622 The initial single-character string in each entry defines the character
4623 you have to press after the dispatcher command `C-c a' in order to
4624 access the command. The second parameter is the search type, followed
4625 by the string or regular expression to be used for the matching. The
4626 example above will therefore define:
4629 as a global search for TODO entries with `WAITING' as the TODO
4633 as the same search, but only in the current buffer and displaying
4634 the results as a sparse tree
4637 as a global tags search for headlines marked `:BOSS:' but not
4641 as the same search as `C-c a u', but limiting the search to
4642 headlines that are also TODO items
4645 as the same search as `C-c a u', but only in the current buffer and
4646 displaying the result as a sparse tree
4649 to create a sparse tree (again: current buffer only) with all
4650 entries containing the word `FIXME'.
4653 File: org, Node: Block agenda, Next: Setting Options, Prev: Storing searches, Up: Custom agenda views
4658 Another possibility is the construction of agenda views that comprise
4659 the results of _several_ commands, each of which creates a block in the
4660 agenda buffer. The available commands include `agenda' for the daily
4661 or weekly agenda (as created with `C-c a a'), `alltodo' for the global
4662 todo list (as constructed with `C-c a t'), and the matching commands
4663 discussed above: `todo', `tags', and `tags-todo'. Here are two
4666 (setq org-agenda-custom-commands
4667 '(("h" "Agenda and Home-related tasks"
4671 ("o" "Agenda and Office-related tasks"
4676 This will define `C-c a h' to create a multi-block view for stuff you
4677 need to attend to at home. The resulting agenda buffer will contain
4678 your agenda for the current week, all TODO items that carry the tag
4679 `HOME', and also all lines tagged with `GARDEN'. Finally the command
4680 `C-c a o' provides a similar view for office tasks.
4683 File: org, Node: Setting Options, Next: Exporting Agenda Views, Prev: Block agenda, Up: Custom agenda views
4685 9.6.3 Setting Options for custom commands
4686 -----------------------------------------
4688 Org-mode contains a number of variables regulating agenda construction
4689 and display. The global variables define the behavior for all agenda
4690 commands, including the custom commands. However, if you want to change
4691 some settings just for a single custom view, you can do so. Setting
4692 options requires inserting a list of variable names and values at the
4693 right spot in `org-agenda-custom-commands'. For example:
4695 (setq org-agenda-custom-commands
4696 '(("w" todo "WAITING"
4697 ((org-agenda-sorting-strategy '(priority-down))
4698 (org-agenda-prefix-format " Mixed: ")))
4699 ("U" tags-tree "+BOSS-URGENT"
4700 ((org-show-following-heading nil)
4701 (org-show-hierarchy-above nil)))))
4703 Now the `C-c a w' command will sort the collected entries only by
4704 priority, and the prefix format is modified to just say ` Mixed:'
4705 instead of giving the category of the entry. The sparse tags tree of
4706 `C-c a U' will now turn out ultra-compact, because neither the headline
4707 hierarchy above the match, nor the headline following the match will be
4710 For command sets creating a block agenda,
4711 `org-agenda-custom-commands' has two separate spots for setting
4712 options. You can add options that should be valid for just a single
4713 command in the set, and options that should be valid for all commands in
4714 the set. The former are just added to the command entry, the latter
4715 must come after the list of command entries. Going back to the block
4716 agenda example (*note Block agenda::), let's change the sorting strategy
4717 for the `C-c a h' commands to `priority-down', but let's sort the
4718 results for GARDEN tags query in the opposite order, `priority-up'.
4719 This would look like this:
4721 (setq org-agenda-custom-commands
4722 '(("h" "Agenda and Home-related tasks"
4726 ((org-agenda-sorting-strategy '(priority-up)))))
4727 ((org-agenda-sorting-strategy '(priority-down))))
4728 ("o" "Agenda and Office-related tasks"
4733 As you see, the values and parenthesis setting is a little complex.
4734 When in doubt, use the customize interface to set this variable - it
4735 fully supports its structure. Just one caveat: When setting options in
4736 this interface, the _values_ are just lisp expressions. So if the
4737 value is a string, you need to add the double quotes around the value
4741 File: org, Node: Exporting Agenda Views, Next: Extracting Agenda Information for other programs, Prev: Setting Options, Up: Custom agenda views
4743 9.6.4 Exporting Agenda Views
4744 ----------------------------
4746 If you are away from your computer, it can be very useful to have a
4747 printed version of some agenda views to carry around. Org-mode can
4748 export custom agenda views as plain text, HTML(1) and postscript. If
4749 you want to do this only occasionally, use the command
4752 Write the agenda view to a file. Depending on the extension of the
4753 selected file name, the view will be exported as HTML (extension
4754 `.html' or `.htm'), Postscript (extension `.ps'), or plain text
4755 (any other extension). Use the variable
4756 `org-agenda-exporter-settings' to set options for `ps-print' and
4757 for `htmlize' to be used during export, for example
4758 (setq org-agenda-exporter-settings
4759 '((ps-number-of-columns 2)
4760 (ps-landscape-mode t)
4761 (htmlize-output-type 'css)))
4763 If you need to export certain agenda views frequently, you can
4764 associate any custom agenda command with a list of output file names
4765 (2). Here is an example that first does define custom commands for the
4766 agenda and the global todo list, together with a number of files to
4767 which to export them. Then we define two block agenda commands and
4768 specify filenames for them as well. File names can be relative to the
4769 current working directory, or absolute.
4771 (setq org-agenda-custom-commands
4772 '(("X" agenda "" nil ("agenda.html" "agenda.ps"))
4773 ("Y" alltodo "" nil ("todo.html" "todo.txt" "todo.ps"))
4774 ("h" "Agenda and Home-related tasks"
4779 ("~/views/home.html"))
4780 ("o" "Agenda and Office-related tasks"
4785 ("~/views/office.ps"))))
4787 The extension of the file name determines the type of export. If it
4788 is `.html', Org-mode will use the `htmlize.el' package to convert the
4789 buffer to HTML and save it to this file name. If the extension is
4790 `.ps', `ps-print-buffer-with-faces' is used to produce postscript
4791 output. Any other extension produces a plain ASCII file.
4793 The export files are _not_ created when you use one of those
4794 commands interactively. Instead, there is a special command to produce
4795 _all_ specified files in one step:
4798 Export all agenda views that have export filenames associated with
4801 You can use the options section of the custom agenda commands to also
4802 set options for the export commands. For example:
4804 (setq org-agenda-custom-commands
4806 ((ps-number-of-columns 2)
4807 (ps-landscape-mode t)
4808 (org-agenda-prefix-format " [ ] ")
4809 (org-agenda-with-colors nil)
4810 (org-agenda-remove-tags t))
4813 This command sets two options for the postscript exporter, to make it
4814 print in two columns in landscape format - the resulting page can be cut
4815 in two and then used in a paper agenda. The remaining settings modify
4816 the agenda prefix to omit category and scheduling information, and
4817 instead include a checkbox to check off items. We also remove the tags
4818 to make the lines compact, and we don't want to use colors for the
4819 black-and-white printer. Settings specified in
4820 `org-agenda-exporter-settings' will also apply, but the settings in
4821 `org-agenda-custom-commands' take precedence.
4823 From the command line you may also use
4824 emacs -f org-batch-store-agenda-views -kill
4825 or, if you need to modify some parameters
4826 emacs -eval '(org-batch-store-agenda-views \
4827 org-agenda-ndays 30 \
4828 org-agenda-include-diary nil \
4829 org-agenda-files (quote ("~/org/project.org")))' \
4831 which will create the agenda views restricted to the file
4832 `~/org/project.org', without diary entries and with 30 days extent.
4834 ---------- Footnotes ----------
4836 (1) You need to install Hrvoje Niksic' `htmlize.el'.
4838 (2) If you want to store standard views like the weekly agenda or
4839 the global TODO list as well, you need to define custom commands for
4840 them in order to be able to specify filenames.
4843 File: org, Node: Extracting Agenda Information for other programs, Prev: Exporting Agenda Views, Up: Custom agenda views
4845 9.6.5 Extracting Agenda Information for other programs
4846 ------------------------------------------------------
4848 Org-mode provides commands to access agenda information for the command
4849 line in emacs batch mode. This extracted information can be sent
4850 directly to a printer, or it can be read by a program that does further
4851 processing of the data. The first of these commands is the function
4852 `org-batch-agenda', that produces an agenda view and sends it as ASCII
4853 text to STDOUT. The command takes a single string as parameter. If
4854 the string has length 1, it is used as a key to one of the commands you
4855 have configured in `org-agenda-custom-commands', basically any key you
4856 can use after `C-c a'. For example, to directly print the current TODO
4859 emacs -batch -l ~/.emacs -eval '(org-batch-agenda "t")' | lpr
4861 If the parameter is a string with 2 or more characters, it is used
4862 as a tags/todo match string. For example, to print your local shopping
4863 list (all items with the tag `shop', but excluding the tag `NewYork'),
4866 emacs -batch -l ~/.emacs \
4867 -eval '(org-batch-agenda "+shop-NewYork")' | lpr
4869 You may also modify parameters on the fly like this:
4871 emacs -batch -l ~/.emacs \
4872 -eval '(org-batch-agenda "a" \
4873 org-agenda-ndays 30 \
4874 org-agenda-include-diary nil \
4875 org-agenda-files (quote ("~/org/project.org")))' \
4878 which will produce a 30 day agenda, fully restricted to the Org file
4879 `~/org/projects.org', not even including the diary.
4881 If you want to process the agenda data in more sophisticated ways,
4882 you can use the command `org-batch-agenda-csv' to get a comma-separated
4883 list of values for each agenda item. Each line in the output will
4884 contain a number of fields separated by commas. The fields in a line
4887 category The category of the item
4888 head The headline, without TODO kwd, TAGS and PRIORITY
4889 type The type of the agenda entry, can be
4890 todo selected in TODO match
4891 tagsmatch selected in tags match
4892 diary imported from diary
4895 timestamp appointment, selected by timestamp
4896 closed entry was closed on date
4897 upcoming-deadline warning about nearing deadline
4898 past-scheduled forwarded scheduled item
4899 block entry has date block including date
4900 todo The todo keyword, if any
4901 tags All tags including inherited ones, separated by colons
4902 date The relevant date, like 2007-2-14
4903 time The time, like 15:00-16:50
4904 extra String with extra planning info
4905 priority-l The priority letter if any was given
4906 priority-n The computed numerical priority
4908 Time and date will only be given if a timestamp (or deadline/scheduled)
4909 lead to the selection of the item.
4911 A CSV list like this is very easy to use in a post processing script.
4912 For example, here is a Perl program that gets the TODO list from
4913 Emacs/org-mode and prints all the items, preceded by a checkbox:
4917 # define the Emacs command to run
4918 $cmd = "emacs -batch -l ~/.emacs -eval '(org-batch-agenda-csv \"t\")'";
4920 # run it and capture the output
4921 $agenda = qx{$cmd 2>/dev/null};
4923 # loop over all lines
4924 foreach $line (split(/\n/,$agenda)) {
4926 # get the individual values
4927 ($category,$head,$type,$todo,$tags,$date,$time,$extra,
4928 $priority_l,$priority_n) = split(/,/,$line);
4930 # proccess and print
4931 print "[ ] $head\n";
4935 File: org, Node: Embedded LaTeX, Next: Exporting, Prev: Agenda views, Up: Top
4940 Plain ASCII is normally sufficient for almost all note taking. One
4941 exception, however, are scientific notes which need to be able to
4942 contain mathematical symbols and the occasional formula. LaTeX(1) is
4943 widely used to typeset scientific documents. Org-mode supports
4944 embedding LaTeX code into its files, because many academics are used to
4945 read LaTeX source code, and because it can be readily processed into
4946 images for HTML production.
4948 It is not necessary to mark LaTeX macros and code in any special way.
4949 If you observe a few conventions, Org-mode knows how to find it and what
4954 * Math symbols:: TeX macros for symbols and Greek letters
4955 * Subscripts and Superscripts:: Simple syntax for raising/lowering text
4956 * LaTeX fragments:: Complex formulas made easy
4957 * Processing LaTeX fragments:: Previewing LaTeX processing
4958 * CDLaTeX mode:: Speed up entering of formulas
4960 ---------- Footnotes ----------
4962 (1) LaTeX is a macro system based on Donald E. Knuth's TeX system.
4963 Many of the features described here as "LaTeX" are really from TeX, but
4964 for simplicity I am blurring this distinction.
4967 File: org, Node: Math symbols, Next: Subscripts and Superscripts, Prev: Embedded LaTeX, Up: Embedded LaTeX
4972 You can use LaTeX macros to insert special symbols like `\alpha' to
4973 indicate the Greek letter, or `\to' to indicate an arrow. Completion
4974 for these macros is available, just type `\' and maybe a few letters,
4975 and press `M-<TAB>' to see possible completions. Unlike LaTeX code,
4976 Org-mode allows these macros to be present without surrounding math
4977 delimiters, for example:
4979 Angles are written as Greek letters \alpha, \beta and \gamma.
4981 During HTML export (*note HTML export::), these symbols are
4982 translated into the proper syntax for HTML, for the above examples this
4983 is `α' and `→', respectively.
4986 File: org, Node: Subscripts and Superscripts, Next: LaTeX fragments, Prev: Math symbols, Up: Embedded LaTeX
4988 10.2 Subscripts and Superscripts
4989 ================================
4991 Just like in LaTeX, `^' and `_' are used to indicate super- and
4992 subscripts. Again, these can be used without embedding them in
4993 math-mode delimiters. To increase the readability of ASCII text, it is
4994 not necessary (but OK) to surround multi-character sub- and superscripts
4995 with curly braces. For example
4997 The mass if the sun is M_sun = 1.989 x 10^30 kg. The radius of
4998 the sun is R_{sun} = 6.96 x 10^8 m.
5000 To avoid interpretation as raised or lowered text, you can quote `^'
5001 and `_' with a backslash: `\_' and `\^'.
5003 During HTML export (*note HTML export::), subscript and superscripts
5004 are surrounded with `<sub>' and `<sup>' tags, respectively.
5007 File: org, Node: LaTeX fragments, Next: Processing LaTeX fragments, Prev: Subscripts and Superscripts, Up: Embedded LaTeX
5009 10.3 LaTeX fragments
5010 ====================
5012 With symbols, sub- and superscripts, HTML is pretty much at its end when
5013 it comes to representing mathematical formulas(1). More complex
5014 expressions need a dedicated formula processor. To this end, Org-mode
5015 can contain arbitrary LaTeX fragments. It provides commands to preview
5016 the typeset result of these fragments, and upon export to HTML, all
5017 fragments will be converted to images and inlined into the HTML
5018 document(2). For this to work you need to be on a system with a working
5019 LaTeX installation. You also need the `dvipng' program, available at
5020 `http://sourceforge.net/projects/dvipng/'. The LaTeX header that will
5021 be used when processing a fragment can be configured with the variable
5022 `org-format-latex-header'.
5024 LaTeX fragments don't need any special marking at all. The following
5025 snippets will be identified as LaTeX source code:
5026 * Environments of any kind. The only requirement is that the
5027 `\begin' statement appears on a new line, preceded by only
5030 * Text within the usual LaTeX math delimiters. To avoid conflicts
5031 with currency specifications, single `$' characters are only
5032 recognized as math delimiters if the enclosed text contains at
5033 most two line breaks, is directly attached to the `$' characters
5034 with no whitespace in between, and if the closing `$' is followed
5035 by whitespace or punctuation. For the other delimiters, there is
5036 no such restriction, so when in doubt, use `\(...\)' as inline
5041 \begin{equation} % arbitrary environments,
5042 x=\sqrt{b} % even tables, figures
5043 \end{equation} % etc
5045 If $a^2=b$ and \( b=2 \), then the solution must be
5046 either $$ a=+\sqrt{2} $$ or \[ a=-\sqrt{2} \].
5048 If you need any of the delimiter ASCII sequences for other purposes, you
5049 can configure the option `org-format-latex-options' to deselect the
5050 ones you do not wish to have interpreted by the LaTeX converter.
5052 ---------- Footnotes ----------
5054 (1) Yes, there is MathML, but that is not yet fully supported by
5055 many browsers, and there is no decent converter for turning LaTeX or
5056 ASCII representations of formulas into MathML. So for the time being,
5057 converting formulas into images seems the way to go.
5059 (2) The LaTeX export will not use images for displaying LaTeX
5060 fragments but include these fragments directly into the LaTeX code.
5063 File: org, Node: Processing LaTeX fragments, Next: CDLaTeX mode, Prev: LaTeX fragments, Up: Embedded LaTeX
5065 10.4 Processing LaTeX fragments
5066 ===============================
5068 LaTeX fragments can be processed to produce a preview images of the
5069 typeset expressions:
5072 Produce a preview image of the LaTeX fragment at point and overlay
5073 it over the source code. If there is no fragment at point,
5074 process all fragments in the current entry (between two
5075 headlines). When called with a prefix argument, process the
5076 entire subtree. When called with two prefix arguments, or when
5077 the cursor is before the first headline, process the entire buffer.
5080 Remove the overlay preview images.
5082 During HTML export (*note HTML export::), all LaTeX fragments are
5083 converted into images and inlined into the document if the following
5086 (setq org-export-with-LaTeX-fragments t)
5089 File: org, Node: CDLaTeX mode, Prev: Processing LaTeX fragments, Up: Embedded LaTeX
5091 10.5 Using CDLaTeX to enter math
5092 ================================
5094 CDLaTeX-mode is a minor mode that is normally used in combination with a
5095 major LaTeX mode like AUCTeX in order to speed-up insertion of
5096 environments and math templates. Inside Org-mode, you can make use of
5097 some of the features of cdlatex-mode. You need to install `cdlatex.el'
5098 and `texmathp.el' (the latter comes also with AUCTeX) from
5099 `http://www.astro.uva.nl/~dominik/Tools/cdlatex'. Don't turn
5100 cdlatex-mode itself under Org-mode, but use the light version
5101 `org-cdlatex-mode' that comes as part of Org-mode. Turn it on for the
5102 current buffer with `M-x org-cdlatex-mode', or for all Org-mode files
5105 (add-hook 'org-mode-hook 'turn-on-org-cdlatex)
5107 When this mode is enabled, the following features are present (for
5108 more details see the documentation of cdlatex-mode):
5109 * Environment templates can be inserted with `C-c {'.
5111 * The <TAB> key will do template expansion if the cursor is inside a
5112 LaTeX fragment(1). For example, <TAB> will expand `fr' to
5113 `\frac{}{}' and position the cursor correctly inside the first
5114 brace. Another <TAB> will get you into the second brace. Even
5115 outside fragments, <TAB> will expand environment abbreviations at
5116 the beginning of a line. For example, if you write `equ' at the
5117 beginning of a line and press <TAB>, this abbreviation will be
5118 expanded to an `equation' environment. To get a list of all
5119 abbreviations, type `M-x cdlatex-command-help'.
5121 * Pressing `_' and `^' inside a LaTeX fragment will insert these
5122 characters together with a pair of braces. If you use <TAB> to
5123 move out of the braces, and if the braces surround only a single
5124 character or macro, they are removed again (depending on the
5125 variable `cdlatex-simplify-sub-super-scripts').
5127 * Pressing the backquote ``' followed by a character inserts math
5128 macros, also outside LaTeX fragments. If you wait more than 1.5
5129 seconds after the backquote, a help window will pop up.
5131 * Pressing the normal quote `'' followed by another character
5132 modifies the symbol before point with an accent or a font. If you
5133 wait more than 1.5 seconds after the backquote, a help window will
5134 pop up. Character modification will work only inside LaTeX
5135 fragments, outside the quote is normal.
5137 ---------- Footnotes ----------
5139 (1) Org-mode has a method to test if the cursor is inside such a
5140 fragment, see the documentation of the function
5141 `org-inside-LaTeX-fragment-p'.
5144 File: org, Node: Exporting, Next: Publishing, Prev: Embedded LaTeX, Up: Top
5149 Org-mode documents can be exported into a variety of other formats. For
5150 printing and sharing of notes, ASCII export produces a readable and
5151 simple version of an Org-mode file. HTML export allows you to publish a
5152 notes file on the web, while the XOXO format provides a solid base for
5153 exchange with a broad range of other applications. LaTeX export lets
5154 you use Org-mode and its structured editing functions to easily create
5155 LaTeX files. To incorporate entries with associated times like
5156 deadlines or appointments into a desktop calendar program like iCal,
5157 Org-mode can also produce extracts in the iCalendar format. Currently
5158 Org-mode only supports export, not import of these different formats.
5160 When exporting, Org-mode uses special conventions to enrich the
5161 output produced. *Note Text interpretation::, for more details.
5164 Dispatcher for export and publishing commands. Displays a
5165 help-window listing the additional key(s) needed to launch an
5166 export or publishing command.
5170 * ASCII export:: Exporting to plain ASCII
5171 * HTML export:: Exporting to HTML
5172 * LaTeX export:: Exporting to LaTeX
5173 * XOXO export:: Exporting to XOXO
5174 * iCalendar export:: Exporting in iCalendar format
5175 * Text interpretation:: How the exporter looks at the file
5178 File: org, Node: ASCII export, Next: HTML export, Prev: Exporting, Up: Exporting
5183 ASCII export produces a simple and very readable version of an Org-mode
5187 Export as ASCII file. For an org file `myfile.org', the ASCII file
5188 will be `myfile.txt'. The file will be overwritten without
5189 warning. If there is an active region, only the region will be
5190 exported. If the selected region is a single tree, the tree head
5191 will become the document title. If the tree head entry has or
5192 inherits an EXPORT_FILE_NAME property, that name will be used for
5196 Export only the visible part of the document.
5198 In the exported version, the first 3 outline levels will become
5199 headlines, defining a general document structure. Additional levels
5200 will be exported as itemized lists. If you want that transition to
5201 occur at a different level, specify it with a prefix argument. For
5206 creates only top level headlines and does the rest as items. When
5207 headlines are converted to items, the indentation of the text following
5208 the headline is changed to fit nicely under the item. This is done with
5209 the assumption that the first bodyline indicates the base indentation of
5210 the body text. Any indentation larger than this is adjusted to preserve
5211 the layout relative to the first line. Should there be lines with less
5212 indentation than the first, these are left alone.
5215 File: org, Node: HTML export, Next: LaTeX export, Prev: ASCII export, Up: Exporting
5220 Org-mode contains an HTML (XHTML 1.0 strict) exporter with extensive
5221 HTML formatting, in ways similar to John Grubers _markdown_ language,
5222 but with additional support for tables.
5226 * HTML Export commands:: How to invoke LaTeX export
5227 * Quoting HTML tags:: Using direct HTML in Org-mode
5228 * Links:: Transformation of links for HTML
5229 * Images:: How to include images
5230 * CSS support:: Changing the appearence of the output
5233 File: org, Node: HTML Export commands, Next: Quoting HTML tags, Prev: HTML export, Up: HTML export
5235 11.2.1 HTML export commands
5236 ---------------------------
5239 Export as HTML file `myfile.html'. For an org file `myfile.org',
5240 the ASCII file will be `myfile.html'. The file will be
5241 overwritten without warning. If there is an active region, only
5242 the region will be exported. If the selected region is a single
5243 tree, the tree head will become the document title. If the tree
5244 head entry has or inherits an EXPORT_FILE_NAME property, that name
5245 will be used for the export.
5248 Export as HTML file and immediately open it with a browser.
5251 Export to a temporary buffer, do not create a file.
5254 Export the active region to a temporary buffer. With prefix arg,
5255 do not produce file header and foot, but just the plain HTML
5256 section for the region. This is good for cut-and-paste operations.
5265 Export only the visible part of the document.
5267 `M-x org-export-region-as-html'
5268 Convert the region to HTML under the assumption that it was
5269 org-mode syntax before. This is a global command that can be
5270 invoked in any buffer.
5272 `M-x org-replace-region-by-HTML'
5273 Replace the active region (assumed to be in Org-mode syntax) by
5276 In the exported version, the first 3 outline levels will become
5277 headlines, defining a general document structure. Additional levels
5278 will be exported as itemized lists. If you want that transition to
5279 occur at a different level, specify it with a prefix argument. For
5284 creates two levels of headings and does the rest as items.
5287 File: org, Node: Quoting HTML tags, Next: Links, Prev: HTML Export commands, Up: HTML export
5289 11.2.2 Quoting HTML tags
5290 ------------------------
5292 Plain `<' and `>' are always transformed to `<' and `>' in HTML
5293 export. If you want to include simple HTML tags which should be
5294 interpreted as such, mark them with `@' as in `@<b>bold text@</b>'.
5295 Note that this really works only for simple tags. For more extensive
5296 HTML that should be copied verbatim to the exported file use either
5298 #+HTML: Literal HTML code for export
5303 All lines between these markers are exported literally
5307 File: org, Node: Links, Next: Images, Prev: Quoting HTML tags, Up: HTML export
5312 Internal links (*note Internal links::) will continue to work in HTML
5313 files only if they match a dedicated `<<target>>'. Automatic links
5314 created by radio targets (*note Radio targets::) will also work in the
5315 HTML file. Links to external files will still work if the HTML file is
5316 in the same directory as the Org-mode file. Links to other `.org'
5317 files will be translated into HTML links under the assumption that an
5318 HTML version also exists of the linked file. For information related to
5319 linking files while publishing them to a publishing directory see *Note
5323 File: org, Node: Images, Next: CSS support, Prev: Links, Up: HTML export
5328 HTML export can inline images given as links in the Org-mode file, and
5329 it can make an image the clickable part of a link. By default(1),
5330 images are inlined if a link does not have a description. So
5331 `[[file:myimg.jpg]]' will be inlined, while `[[file:myimg.jpg][the
5332 image]]' will just produce a link `the image' that points to the image.
5333 If the description part itself is a `file:' link or a `http:' URL
5334 pointing to an image, this image will be inlined and activated so that
5335 clicking on the image will activate the link. For example, to include
5336 a thumbnail that will link to a high resolution version of the image,
5339 [[file:highres.jpg][file:thumb.jpg]]
5341 and you could use `http' addresses just as well.
5343 ---------- Footnotes ----------
5345 (1) but see the variable `org-export-html-inline-images'
5348 File: org, Node: CSS support, Prev: Images, Up: HTML export
5353 You can also give style information for the exported file. The HTML
5354 exporter assigns the following CSS classes to appropriate parts of the
5355 document - your style specifications may change these:
5357 .done the DONE keyword
5358 .timestamp time stamp
5359 .timestamp-kwd keyword associated with a time stamp, like SCHEDULED
5360 .tag tag in a headline
5361 .target target for links
5363 The default style specification can be configured through the option
5364 `org-export-html-style'. If you want to use a file-local style, you
5365 may use file variables, best wrapped into a COMMENT section at the end
5366 of the outline tree. For example(1):
5368 * COMMENT html style specifications
5371 # org-export-html-style: " <style type=\"text/css\">
5372 # p {font-weight: normal; color: gray; }
5373 # h1 {color: black; }
5377 Remember to execute `M-x normal-mode' after changing this to make
5378 the new style visible to Emacs. This command restarts org-mode for the
5379 current buffer and forces Emacs to re-evaluate the local variables
5380 section in the buffer.
5382 ---------- Footnotes ----------
5384 (1) Under Emacs 21, the continuation lines for a variable value
5385 should have no `#' at the start of the line.
5388 File: org, Node: LaTeX export, Next: XOXO export, Prev: HTML export, Up: Exporting
5393 Org-mode contains a LaTeX exporter written by Bastien Guerry.
5397 * LaTeX export commands:: How to invoke LaTeX export
5398 * Quoting LaTeX code:: Incorporating literal LaTeX code
5401 File: org, Node: LaTeX export commands, Next: Quoting LaTeX code, Prev: LaTeX export, Up: LaTeX export
5403 11.3.1 LaTeX export commands
5404 ----------------------------
5407 Export as LaTeX file `myfile.tex'.
5410 Export to a temporary buffer, do not create a file.
5415 Export only the visible part of the document.
5417 `M-x org-export-region-as-latex'
5418 Convert the region to LaTeX under the assumption that it was
5419 org-mode syntax before. This is a global command that can be
5420 invoked in any buffer.
5422 `M-x org-replace-region-by-latex'
5423 Replace the active region (assumed to be in Org-mode syntax) by
5426 In the exported version, the first 3 outline levels will become
5427 headlines, defining a general document structure. Additional levels
5428 will be exported as description lists. The exporter can ignore them or
5429 convert them to a custom string depending on `org-latex-low-levels'.
5431 If you want that transition to occur at a different level, specify it
5432 with a prefix argument. For example,
5436 creates two levels of headings and does the rest as items.
5439 File: org, Node: Quoting LaTeX code, Prev: LaTeX export commands, Up: LaTeX export
5441 11.3.2 Quoting LaTeX code
5442 -------------------------
5444 Embedded LaTeX as described in *Note Embedded LaTeX:: will be correctly
5445 inserted into the LaTeX file. Forthermore, you can add special code
5446 that should only be present in LaTeX export with the following
5449 #+LaTeX: Literal LaTeX code for export
5454 All lines between these markers are exported literally
5458 File: org, Node: XOXO export, Next: iCalendar export, Prev: LaTeX export, Up: Exporting
5463 Org-mode contains an exporter that produces XOXO-style output.
5464 Currently, this exporter only handles the general outline structure and
5465 does not interpret any additional Org-mode features.
5468 Export as XOXO file `myfile.html'.
5471 Export only the visible part of the document.
5474 File: org, Node: iCalendar export, Next: Text interpretation, Prev: XOXO export, Up: Exporting
5476 11.5 iCalendar export
5477 =====================
5479 Some people like to use Org-mode for keeping track of projects, but
5480 still prefer a standard calendar application for anniversaries and
5481 appointments. In this case it can be useful to have deadlines and
5482 other time-stamped items in Org-mode files show up in the calendar
5483 application. Org-mode can export calendar information in the standard
5484 iCalendar format. If you also want to have TODO entries included in the
5485 export, configure the variable `org-icalendar-include-todo'.
5488 Create iCalendar entries for the current file and store them in
5489 the same directory, using a file extension `.ics'.
5492 Like `C-c C-e i', but do this for all files in `org-agenda-files'.
5493 For each of these files, a separate iCalendar file will be
5497 Create a single large iCalendar file from all files in
5498 `org-agenda-files' and write it to the file given by
5499 `org-combined-agenda-icalendar-file'.
5501 How this calendar is best read and updated, depends on the
5502 application you are using. The FAQ covers this issue.
5505 File: org, Node: Text interpretation, Prev: iCalendar export, Up: Exporting
5507 11.6 Text interpretation by the exporter
5508 ========================================
5510 The exporter backends interpret additional structure in the Org-mode
5511 file in order to produce better output.
5515 * Comment lines:: Some lines will not be exported
5516 * Initial text:: Text before the first headline
5517 * Footnotes:: Numbers like [1]
5518 * Enhancing text:: Subscripts, symbols and more
5519 * Export options:: How to influence the export settings
5522 File: org, Node: Comment lines, Next: Initial text, Prev: Text interpretation, Up: Text interpretation
5524 11.6.1 Comment lines
5525 --------------------
5527 Lines starting with `#' in column zero are treated as comments and will
5528 never be exported. Also entire subtrees starting with the word
5529 `COMMENT' will never be exported.
5532 Toggle the COMMENT keyword at the beginning of an entry.
5535 File: org, Node: Initial text, Next: Footnotes, Prev: Comment lines, Up: Text interpretation
5537 11.6.2 Text before the first headline
5538 -------------------------------------
5540 Org-mode normally ignores any text before the first headline when
5541 exporting, leaving this region for internal links to speed up navigation
5542 etc. However, in publishing-oriented files, you might want to have some
5543 text before the first headline, like a small introduction, special HTML
5544 code with a navigation bar, etc. You can ask to have this part of the
5545 file exported as well by setting the variable
5546 `org-export-skip-text-before-1st-heading' to `nil'. On a per-file
5547 basis, you can get the same effect with
5551 The text before the first headline will be fully processed (*note
5552 Enhancing text::), and the first non-comment line becomes the title of
5553 the exported document. If you need to include literal HTML, use the
5554 special constructs described in *Note Quoting HTML tags::. The table
5555 of contents is normally inserted directly before the first headline of
5556 the file. If you would like to get it to a different location, insert
5557 the string `[TABLE-OF-CONTENTS]' on a line by itself at the desired
5560 Finally, if you want to use the space before the first headline for
5561 internal purposes, but _still_ want to place something before the first
5562 headline when exporting the file, you can use the `#+TEXT' construct:
5565 #+TEXT: This text will go before the *first* headline.
5566 #+TEXT: We place the table of contents here:
5567 #+TEXT: [TABLE-OF-CONTENTS]
5568 #+TEXT: This goes between the table of contents and the first headline
5571 File: org, Node: Footnotes, Next: Enhancing text, Prev: Initial text, Up: Text interpretation
5576 Numbers in square brackets are treated as footnotes, so that you can use
5577 the Emacs package `footnote.el' to create footnotes. For example:
5579 The org-mode homepage[1] clearly needs help from
5580 a good web designer.
5582 [1] The link is: http://www.astro.uva.nl/~dominik/Tools/org
5584 Note that the `footnote' package uses `C-c !' to invoke its commands.
5585 This binding conflicts with the org-mode command for inserting inactive
5586 time stamps. You could use the variable `footnote-prefix' to switch
5587 footnotes commands to another key. Or, if you are too used to this
5588 binding, you could use `org-replace-disputed-keys' and
5589 `org-disputed-keys' to change the settings in Org-mode.
5592 File: org, Node: Enhancing text, Next: Export options, Prev: Footnotes, Up: Text interpretation
5594 11.6.4 Enhancing text for export
5595 --------------------------------
5597 Some of the export backends of Org-mode allow for sophisticated text
5598 formatting, this is true in particular for the HTML and LaTeX backends.
5599 Org-mode has a number of typing conventions that allow to produce a
5600 richly formatted output.
5602 * Plain lists `-', `*' or `+' as bullet, or with `1.' or `2)' as
5603 enumerator will be recognized and transformed if the backend
5604 supports lists. See *Note Plain lists::.
5606 * You can make words *bold*, /italic/, _underlined_, `=code=', and
5607 even `+strikethrough+'(1).
5609 * A line consisting of only dashes, and at least 5 of them, will be
5610 exported as a horizontal line (`<hr/>' in HTML).
5612 * Many TeX macros and entire LaTeX fragments are converted into HTML
5613 entities or images (*note Embedded LaTeX::).
5615 * Tables are transformed into native tables under the exporter, if
5616 the export backend supports this. Data fields before the first
5617 horizontal separator line will be formatted as table header fields.
5619 * If a headline starts with the word `QUOTE', the text below the
5620 headline will be typeset as fixed-width, to allow quoting of
5621 computer codes etc. Lines starting with `:' are also typeset in
5624 Toggle fixed-width for entry (QUOTE) or region, see below.
5626 * A double backslash _at the end of a line_ enforces a line break at
5629 If these conversions conflict with your habits of typing ASCII text,
5630 they can all be turned off with corresponding variables. See the
5631 customization group `org-export-general', and the following section
5632 which explains how to set export options with special lines in a buffer.
5634 ---------- Footnotes ----------
5636 (1) but remember that strikethrough is typographically evil and
5637 should never be used.
5640 File: org, Node: Export options, Prev: Enhancing text, Up: Text interpretation
5642 11.6.5 Export options
5643 ---------------------
5645 The exporter recognizes special lines in the buffer which provide
5646 additional information. These lines may be put anywhere in the file.
5647 The whole set of lines can be inserted into the buffer with `C-c C-e
5648 t'. For individual lines, a good way to make sure the keyword is
5649 correct is to type `#+' and then use `M-<TAB>' completion (*note
5653 Insert template with export options, see example below.
5655 #+TITLE: the title to be shown (default is the buffer name)
5656 #+AUTHOR: the author (default taken from `user-full-name')
5657 #+EMAIL: his/her email address (default from `user-mail-address')
5658 #+LANGUAGE: language for HTML, e.g. `en' (`org-export-default-language')
5659 #+TEXT: Some descriptive text to be inserted at the beginning.
5660 #+TEXT: Several lines may be given.
5661 #+OPTIONS: H:2 num:t toc:t \n:nil @:t ::t |:t ^:t f:t TeX:t ...
5663 The OPTIONS line is a compact form to specify export settings. Here
5665 H: set the number of headline levels for export
5666 num: turn on/off section-numbers
5667 toc: turn on/off table of contents, or set level limit (integer)
5668 \n: turn on/off linebreak-preservation
5669 @: turn on/off quoted HTML tags
5670 :: turn on/off fixed-width sections
5671 |: turn on/off tables
5672 ^: turn on/off TeX-like syntax for sub- and superscripts. If
5673 you write "^:{}", `a_{b}' will be interpreted, but
5674 the simple `a_b' will be left as it is.
5675 f: turn on/off foototes like this[1].
5676 *: turn on/off emphasized text (bold, italic, underlined)
5677 TeX: turn on/off simple TeX macros in plain text
5678 LaTeX: turn on/off LaTeX fragments
5679 skip: turn on/off skipping the text before the first heading
5680 author: turn on/off inclusion of author name/email into exported file
5681 timestamp: turn on/off inclusion creation time into exported file
5683 These options take effect in both the HTML and LaTeX export, except
5684 for `TeX' and `LaTeX', which are respectively `t' and `nil' for the
5688 File: org, Node: Publishing, Next: Miscellaneous, Prev: Exporting, Up: Top
5693 Org-mode includes(1) a publishing management system that allows you to
5694 configure automatic HTML conversion of _projects_ composed of
5695 interlinked org files. This system is called _org-publish_. You can
5696 also configure org-publish to automatically upload your exported HTML
5697 pages and related attachments, such as images and source code files, to
5698 a web server. Org-publish turns org-mode into a web-site authoring tool.
5700 You can also use Org-publish to convert files into LaTeX, or even
5701 combine HTML and LaTeX conversion so that files are available in both
5702 formats on the server(2).
5704 Org-publish has been contributed to Org-mode by David O'Toole.
5708 * Configuration:: Defining projects
5709 * Sample configuration:: Example projects
5710 * Triggering publication:: Publication commands
5712 ---------- Footnotes ----------
5714 (1) `org-publish.el' is not distributed with Emacs 21, if you are
5715 still using Emacs 21, you need you need to download this file
5718 (2) Since LaTeX files on a server are not that helpful, you surely
5719 want to perform further conversion on them - e.g. convert them to `PDF'
5723 File: org, Node: Configuration, Next: Sample configuration, Prev: Publishing, Up: Publishing
5728 Publishing needs significant configuration to specify files, destination
5729 and many other properties of a project.
5733 * Project alist:: The central configuration variable
5734 * Sources and destinations:: From here to there
5735 * Selecting files:: What files are part of the project?
5736 * Publishing action:: Setting the function doing the publishing
5737 * Publishing options:: Tweaking HTML export
5738 * Publishing links:: Which links keep working after publishing?
5739 * Project page index:: Publishing a list of project files
5742 File: org, Node: Project alist, Next: Sources and destinations, Prev: Configuration, Up: Configuration
5744 12.1.1 The variable `org-publish-project-alist'
5745 -----------------------------------------------
5747 Org-publish is configured almost entirely through setting the value of
5748 one variable, called `org-publish-project-alist'. Each element of the
5749 list configures one project, and may be in one of the two following
5752 ("project-name" :property value :property value ...)
5756 ("project-name" :components ("project-name" "project-name" ...))
5758 In both cases, projects are configured by specifying property values.
5759 A project defines the set of files that will be published, as well as
5760 the publishing configuration to use when publishing those files. When
5761 a project takes the second form listed above, the individual members of
5762 the "components" property are taken to be components of the project,
5763 which group together files requiring different publishing options. When
5764 you publish such a "meta-project" all the components will also publish.
5767 File: org, Node: Sources and destinations, Next: Selecting files, Prev: Project alist, Up: Configuration
5769 12.1.2 Sources and destinations for files
5770 -----------------------------------------
5772 Most properties are optional, but some should always be set. In
5773 particular, org-publish needs to know where to look for source files,
5774 and where to put published files.
5776 `:base-directory' Directory containing publishing source files
5777 `:publishing-directory'Directory (possibly remote) where output files
5779 `:preparation-function'Function called before starting publishing
5780 process, for example to run `make' for updating
5781 files to be published.
5784 File: org, Node: Selecting files, Next: Publishing action, Prev: Sources and destinations, Up: Configuration
5786 12.1.3 Selecting files
5787 ----------------------
5789 By default, all files with extension `.org' in the base directory are
5790 considered part of the project. This can be modified by setting the
5792 `:base-extension' Extension (without the dot!) of source files. This
5793 actually is a regular expression.
5794 `:exclude' Regular expression to match file names that should
5795 not be published, even though they have been selected
5796 on the basis of their extension.
5797 `:include' List of files to be included regardless of
5798 `:base-extension' and `:exclude'.
5801 File: org, Node: Publishing action, Next: Publishing options, Prev: Selecting files, Up: Configuration
5803 12.1.4 Publishing Action
5804 ------------------------
5806 Publishing means that a file is copied to the destination directory and
5807 possibly transformed in the process. The default transformation is to
5808 export Org-mode files as HTML files, and this is done by the function
5809 `org-publish-org-to-html' which calls the HTML exporter (*note HTML
5810 export::). But you also can publish your files in LaTeX by using the
5811 function `org-publish-org-to-latex' instead. Other files like images
5812 only need to be copied to the publishing destination. For non-Org-mode
5813 files, you need to specify the publishing function.
5815 `:publishing-function' Function executing the publication of a file.
5816 This may also be a list of functions, which will
5817 all be called in turn.
5819 The function must accept two arguments: a property list containing at
5820 least a `:publishing-directory' property, and the name of the file to
5821 be published. It should take the specified file, make the necessary
5822 transformation (if any) and place the result into the destination
5823 folder. You can write your own publishing function, but `org-publish'
5824 provides one for attachments (files that only need to be copied):
5825 `org-publish-attachment'.
5828 File: org, Node: Publishing options, Next: Publishing links, Prev: Publishing action, Up: Configuration
5830 12.1.5 Options for the HTML/LaTeX exporters
5831 -------------------------------------------
5833 The property list can be used to set many export options for the HTML
5834 and LaTeX exporters. In most cases, these properties correspond to user
5835 variables in Org-mode. The table below lists these properties along
5836 with the variable they belong to. See the documentation string for the
5837 respective variable for details.
5839 `:language' `org-export-default-language'
5840 `:headline-levels' `org-export-headline-levels'
5841 `:section-numbers' `org-export-with-section-numbers'
5842 `:table-of-contents' `org-export-with-toc'
5843 `:archived-trees' `org-export-with-archived-trees'
5844 `:emphasize' `org-export-with-emphasize'
5845 `:sub-superscript' `org-export-with-sub-superscripts'
5846 `:TeX-macros' `org-export-with-TeX-macros'
5847 `:LaTeX-fragments' `org-export-with-LaTeX-fragments'
5848 `:fixed-width' `org-export-with-fixed-width'
5849 `:timestamps' `org-export-with-timestamps'
5851 `:tags' `org-export-with-tags'
5853 `:tables' `org-export-with-tables'
5854 `:table-auto-headline' `org-export-highlight-first-table-line'
5855 `:style' `org-export-html-style'
5856 `:convert-org-links' `org-export-html-link-org-files-as-html'
5857 `:inline-images' `org-export-html-inline-images'
5858 `:expand-quoted-html' `org-export-html-expand'
5859 `:timestamp' `org-export-html-with-timestamp'
5860 `:publishing-directory'`org-export-publishing-directory'
5861 `:preamble' `org-export-html-preamble'
5862 `:postamble' `org-export-html-postamble'
5863 `:auto-preamble' `org-export-html-auto-preamble'
5864 `:auto-postamble' `org-export-html-auto-postamble'
5865 `:author' `user-full-name'
5866 `:email' `user-mail-address'
5868 Most of the `org-export-with-*' variables have the same effect in
5869 both HTML and LaTeX exporters, except for `:TeX-macros' and
5870 `:LaTeX-fragments', respectively `nil' and `t' in the LaTeX export.
5872 When a property is given a value in org-publish-project-alist, its
5873 setting overrides the value of the corresponding user variable (if any)
5874 during publishing. Options set within a file (*note Export options::),
5875 however, override everything.
5878 File: org, Node: Publishing links, Next: Project page index, Prev: Publishing options, Up: Configuration
5880 12.1.6 Links between published files
5881 ------------------------------------
5883 To create a link from one Org-mode file to another, you would use
5884 something like `[[file:foo.org][The foo]]' or simply `file:foo.org.'
5885 (*note Hyperlinks::). Upon publishing this link becomes a link to
5886 `foo.html'. In this way, you can interlink the pages of your "org web"
5887 project and the links will work as expected when you publish them to
5890 You may also link to related files, such as images. Provided you are
5891 careful with relative pathnames, and provided you have also configured
5892 org-publish to upload the related files, these links will work too.
5893 *Note Complex example:: for an example of this usage.
5895 Sometime an Org-mode file to be published may contain links that are
5896 only valid in your production environment, but not in the publishing
5897 location. In this case, use the property
5899 `:link-validation-function' Function to validate links
5901 to define a function for checking link validity. This function must
5902 accept two arguments, the file name and a directory relative to which
5903 the file name is interpreted in the production environment. If this
5904 function returns `nil', then the HTML generator will only insert a
5905 description into the HTML file, but no link. One option for this
5906 function is `org-publish-validate-link' which checks if the given file
5907 is part of any project in `org-publish-project-alist'.
5910 File: org, Node: Project page index, Prev: Publishing links, Up: Configuration
5912 12.1.7 Project page index
5913 -------------------------
5915 The following properties may be used to control publishing of an index
5916 of files or summary page for a given project.
5918 `:auto-index' When non-nil, publish an index during
5919 org-publish-current-project or org-publish-all.
5920 `:index-filename' Filename for output of index. Defaults to `index.org'
5921 (which becomes `index.html').
5922 `:index-title' Title of index page. Defaults to name of file.
5923 `:index-function' Plugin function to use for generation of index.
5924 Defaults to `org-publish-org-index', which generates
5925 a plain list of links to all files in the project.
5928 File: org, Node: Sample configuration, Next: Triggering publication, Prev: Configuration, Up: Publishing
5930 12.2 Sample configuration
5931 =========================
5933 Below we provide two example configurations. The first one is a simple
5934 project publishing only a set of Org-mode files. The second example is
5935 more complex, with a multi-component project.
5939 * Simple example:: One-component publishing
5940 * Complex example:: A multi-component publishing example
5943 File: org, Node: Simple example, Next: Complex example, Prev: Sample configuration, Up: Sample configuration
5945 12.2.1 Example: simple publishing configuration
5946 -----------------------------------------------
5948 This example publishes a set of Org-mode files to the `public_html'
5949 directory on the local machine.
5951 (setq org-publish-project-alist
5953 :base-directory "~/org/"
5954 :publishing-directory "~/public_html"
5955 :section-numbers nil
5956 :table-of-contents nil
5957 :style "<link rel=stylesheet
5958 href=\"../other/mystyle.css\"
5959 type=\"text/css\">")))
5962 File: org, Node: Complex example, Prev: Simple example, Up: Sample configuration
5964 12.2.2 Example: complex publishing configuration
5965 ------------------------------------------------
5967 This more complicated example publishes an entire website, including
5968 org files converted to HTML, image files, emacs lisp source code, and
5969 stylesheets. The publishing-directory is remote and private files are
5972 To ensure that links are preserved, care should be taken to replicate
5973 your directory structure on the web server, and to use relative file
5974 paths. For example, if your org files are kept in `~/org' and your
5975 publishable images in `~/images', you'd link to an image with
5976 file:../images/myimage.png
5977 On the web server, the relative path to the image should be the
5978 same. You can accomplish this by setting up an "images" folder in the
5979 right place on the webserver, and publishing images to it.
5981 (setq org-publish-project-alist
5983 :base-directory "~/org/"
5984 :base-extension "org"
5985 :publishing-directory "/ssh:user@host:~/html/notebook/"
5986 :publishing-function org-publish-org-to-html
5987 :exclude "PrivatePage.org" ;; regexp
5989 :section-numbers nil
5990 :table-of-contents nil
5991 :style "<link rel=stylesheet
5992 href=\"../other/mystyle.css\" type=\"text/css\">"
5994 :auto-postamble nil)
5997 :base-directory "~/images/"
5998 :base-extension "jpg\\|gif\\|png"
5999 :publishing-directory "/ssh:user@host:~/html/images/"
6000 :publishing-function org-publish-attachment)
6003 :base-directory "~/other/"
6004 :base-extension "css\\|el"
6005 :publishing-directory "/ssh:user@host:~/html/other/"
6006 :publishing-function org-publish-attachment)
6007 ("website" :components ("orgfiles" "images" "other"))))
6010 File: org, Node: Triggering publication, Prev: Sample configuration, Up: Publishing
6012 12.3 Triggering publication
6013 ===========================
6015 Once org-publish is properly configured, you can publish with the
6016 following functions:
6019 Prompt for a specific project and publish all files that belong to
6023 Publish the project containing the current file.
6026 Publish only the current file.
6029 Publish all projects.
6031 Org uses timestamps to track when a file has changed. The above
6032 functions normally only publish changed files. You can override this and
6033 force publishing of all files by giving a prefix argument.
6036 File: org, Node: Miscellaneous, Next: Extensions and Hacking, Prev: Publishing, Up: Top
6043 * Completion:: M-TAB knows what you need
6044 * Customization:: Adapting Org-mode to your taste
6045 * In-buffer settings:: Overview of the #+KEYWORDS
6046 * The very busy C-c C-c key:: When in doubt, press C-c C-c
6047 * Clean view:: Getting rid of leading stars in the outline
6048 * TTY keys:: Using Org-mode on a tty
6049 * Interaction:: Other Emacs packages
6050 * Bugs:: Things which do not work perfectly
6053 File: org, Node: Completion, Next: Customization, Prev: Miscellaneous, Up: Miscellaneous
6058 Org-mode supports in-buffer completion. This type of completion does
6059 not make use of the minibuffer. You simply type a few letters into the
6060 buffer and use the key to complete text right there.
6063 Complete word at point
6064 * At the beginning of a headline, complete TODO keywords.
6066 * After `\', complete TeX symbols supported by the exporter.
6068 * After `*', complete headlines in the current buffer so that
6069 they can be used in search links like `[[*find this
6072 * After `:' in a headline, complete tags. The list of tags is
6073 taken from the variable `org-tag-alist' (possibly set through
6074 the `#+TAGS' in-buffer option, *note Setting tags::), or it
6075 is created dynamically from all tags used in the current
6078 * After `:' and not in a headline, complete property keys. The
6079 list of keys is constructed dynamically from all keys used in
6082 * After `[', complete link abbreviations (*note Link
6085 * After `#+', complete the special keywords like `TYP_TODO' or
6086 `OPTIONS' which set file-specific options for Org-mode. When
6087 the option keyword is already complete, pressing `M-<TAB>'
6088 again will insert example settings for this keyword.
6090 * In the line after `#+STARTUP: ', complete startup keywords,
6091 i.e. valid keys for this line.
6093 * Elsewhere, complete dictionary words using ispell.
6096 File: org, Node: Customization, Next: In-buffer settings, Prev: Completion, Up: Miscellaneous
6101 There are more than 180 variables that can be used to customize
6102 Org-mode. For the sake of compactness of the manual, I am not
6103 describing the variables here. A structured overview of customization
6104 variables is available with `M-x org-customize'. Or select `Browse Org
6105 Group' from the `Org->Customization' menu. Many settings can also be
6106 activated on a per-file basis, by putting special lines into the buffer
6107 (*note In-buffer settings::).
6110 File: org, Node: In-buffer settings, Next: The very busy C-c C-c key, Prev: Customization, Up: Miscellaneous
6112 13.3 Summary of in-buffer settings
6113 ==================================
6115 Org-mode uses special lines in the buffer to define settings on a
6116 per-file basis. These lines start with a `#+' followed by a keyword, a
6117 colon, and then individual words defining a setting. Several setting
6118 words can be in the same line, but you can also have multiple lines for
6119 the keyword. While these settings are described throughout the manual,
6120 here is a summary. After changing any of those lines in the buffer,
6121 press `C-c C-c' with the cursor still in the line to activate the
6122 changes immediately. Otherwise they become effective only when the
6123 file is visited again in a new Emacs session.
6125 `#+ARCHIVE: %s_done::'
6126 This line sets the archive location for the agenda file. It
6127 applies for all subsequent lines until the next `#+ARCHIVE' line,
6128 or the end of the file. The first such line also applies to any
6129 entries before it. The corresponding variable is
6130 `org-archive-location'.
6133 This line sets the category for the agenda file. The category
6134 applies for all subsequent lines until the next `#+CATEGORY' line,
6135 or the end of the file. The first such line also applies to any
6138 `#+COLUMNS: %25ITEM .....'
6139 Set the default format for columns view. This format applies when
6140 columns view is invoked in location where no COLUMNS property
6143 `#+CONSTANTS: name1=value1 ...'
6144 Set file-local values for constants to be used in table formulas.
6145 This line set the local variable
6146 `org-table-formula-constants-local'. The global version of theis
6147 variable is `org-table-formula-constants'. corresponding
6149 `#+LINK: linkword replace'
6150 These lines (several are allowed) specify link abbreviations.
6151 *Note Link abbreviations::. The corresponding variable is
6152 `org-link-abbrev-alist'.
6154 `#+PRIORITIES: highest lowest default'
6155 This line sets the limits and the default for the priorities. All
6156 three must be either letters A-Z or numbers 0-9. The highest
6157 priority must have a lower ASCII number that the lowest priority.
6159 `#+PROPERTY: Property_Name Value'
6160 This line sets a default inheritance value for entries in the
6161 current buffer, most useful for specifying the allowed values of a
6165 This line sets options to be used at startup of Org-mode, when an
6166 Org-mode file is being visited. The first set of options deals
6167 with the initial visibility of the outline tree. The
6168 corresponding variable for global default settings is
6169 `org-startup-folded', with a default value `t', which means
6171 overview top-level headlines only
6172 content all headlines
6173 showall no folding at all, show everything
6174 Then there are options for aligning tables upon visiting a file.
6175 This is useful in files containing narrowed table columns. The
6176 corresponding variable is `org-startup-align-all-tables', with a
6177 default value `nil'.
6178 align align all tables
6179 noalign don't align tables on startup
6180 Logging TODO state changes and clock intervals (variable
6181 `org-log-done') can be configured using these options.
6182 logging record a timestamp when an item is marked DONE
6183 nologging don't record when items are marked DONE
6184 lognotedone record timestamp and a note when DONE
6185 lognotestate record timestamp and a note when TODO state changes
6186 logrepeat record a note when re-instating a repeating item
6187 nologrepeat do not record when re-instating repeating item
6188 lognoteclock-out record timestamp and a note when clocking out
6189 Here are the options for hiding leading stars in outline headings.
6190 The corresponding variables are `org-hide-leading-stars' and
6191 `org-odd-levels-only', both with a default setting `nil' (meaning
6192 `showstars' and `oddeven').
6193 hidestars make all but one of the stars starting a headline invisible.
6194 showstars show all stars starting a headline
6195 odd allow only odd outline levels (1,3,...)
6196 oddeven allow all outline levels
6197 To turn on custom format overlays over time stamps (variables
6198 `org-put-time-stamp-overlays' and
6199 `org-time-stamp-overlay-formats'), use
6200 customtime overlay custom time format
6201 The following options influence the table spreadsheet (variable
6202 `constants-unit-system').
6203 constcgs `constants.el' should use the c-g-s unit system
6204 constSI `constants.el' should use the SI unit system
6206 `#+TAGS: TAG1(c1) TAG2(c2)'
6207 These lines (several such lines are allowed) specify the legal
6208 tags in this file, and (potentially) the corresponding _fast tag
6209 selection_ keys. The corresponding variable is `org-tag-alist'.
6212 This line contains the formulas for the table directly above the
6215 `#+TITLE:, #+AUTHOR:, #+EMAIL:, #+LANGUAGE:, #+TEXT:, #+OPTIONS:'
6216 These lines provide settings for exporting files. For more
6217 details see *Note Export options::.
6219 `#+SEQ_TODO: #+TYP_TODO:'
6220 These lines set the TODO keywords and their interpretation in the
6221 current file. The corresponding variables are `org-todo-keywords'
6222 and `org-todo-interpretation'.
6225 File: org, Node: The very busy C-c C-c key, Next: Clean view, Prev: In-buffer settings, Up: Miscellaneous
6227 13.4 The very busy C-c C-c key
6228 ==============================
6230 The key `C-c C-c' has many purposes in org-mode, which are all
6231 mentioned scattered throughout this manual. One specific function of
6232 this key is to add _tags_ to a headline (*note Tags::). In many other
6233 circumstances it means something like _Hey Org-mode, look here and
6234 update according to what you see here_. Here is a summary of what this
6235 means in different contexts.
6237 - If there are highlights in the buffer from the creation of a sparse
6238 tree, or from clock display, remove these highlights.
6240 - If the cursor is in one of the special `#+KEYWORD' lines, this
6241 triggers scanning the buffer for these lines and updating the
6244 - If the cursor is inside a table, realign the table. This command
6245 works even if the automatic table editor has been turned off.
6247 - If the cursor is on a `#+TBLFM' line, re-apply the formulas to the
6250 - If the cursor is inside a table created by the `table.el' package,
6251 activate that table.
6253 - If the current buffer is a remember buffer, close the note and
6254 file it. With a prefix argument, file it, without further
6255 interaction, to the default location.
6257 - If the cursor is on a `<<<target>>>', update radio targets and
6258 corresponding links in this buffer.
6260 - If the cursor is in a property line or at the start or end of a
6261 property drawer, offer property commands.
6263 - If the cursor is in a plain list item with a checkbox, toggle the
6264 status of the checkbox.
6266 - If the cursor is on a numbered item in a plain list, renumber the
6270 File: org, Node: Clean view, Next: TTY keys, Prev: The very busy C-c C-c key, Up: Miscellaneous
6272 13.5 A cleaner outline view
6273 ===========================
6275 Some people find it noisy and distracting that the Org-mode headlines
6276 are starting with a potentially large number of stars. For example the
6277 tree from *Note Headlines:::
6279 * Top level headline
6285 * Another top level headline
6287 Unfortunately this is deeply ingrained into the code of Org-mode and
6288 cannot be easily changed. You can, however, modify the display in such
6289 a way that all leading stars become invisible and the outline more easy
6290 to read. To do this, customize the variable `org-hide-leading-stars'
6293 (setq org-hide-leading-stars t)
6295 or change this on a per-file basis with one of the lines (anywhere in
6298 #+STARTUP: showstars
6299 #+STARTUP: hidestars
6301 Press `C-c C-c' with the cursor in a `STARTUP' line to activate the
6304 With stars hidden, the tree becomes:
6306 * Top level headline
6312 * Another top level headline
6314 Note that the leading stars are not truly replaced by whitespace, they
6315 are only fontified with the face `org-hide' that uses the background
6316 color as font color. If you are not using either white or black
6317 background, you may have to customize this face to get the wanted
6318 effect. Another possibility is to set this font such that the extra
6319 stars are almost invisible, for example using the color `grey90' on a
6322 Things become cleaner still if you skip all the even levels and use
6323 only odd levels 1, 3, 5..., effectively adding two stars to go from one
6324 outline level to the next:
6326 * Top level headline
6332 * Another top level headline
6334 In order to make the structure editing and export commands handle this
6335 convention correctly, use
6337 (setq org-odd-levels-only t)
6339 or set this on a per-file basis with one of the following lines (don't
6340 forget to press `C-c C-c' with the cursor in the startup line to
6341 activate changes immediately).
6346 You can convert an Org-mode file from single-star-per-level to the
6347 double-star-per-level convention with `M-x org-convert-to-odd-levels
6348 RET' in that file. The reverse operation is `M-x
6349 org-convert-to-oddeven-levels'.
6352 File: org, Node: TTY keys, Next: Interaction, Prev: Clean view, Up: Miscellaneous
6354 13.6 Using org-mode on a tty
6355 ============================
6357 Org-mode uses a number of keys that are not accessible on a tty. This
6358 applies to most special keys like cursor keys, <TAB> and <RET>, when
6359 these are combined with modifier keys like <Meta> and/or <Shift>.
6360 Org-mode uses these bindings because it needs to provide keys for a
6361 large number of commands, and because these keys appeared particularly
6362 easy to remember. In order to still be able to access the core
6363 functionality of Org-mode on a tty, alternative bindings are provided.
6364 Here is a complete list of these bindings, which are obviously more
6365 cumbersome to use. Note that sometimes a work-around can be better.
6366 For example changing a time stamp is really only fun with `S-<cursor>'
6367 keys. On a tty you would rather use `C-c .' to re-insert the
6370 Default Alternative 1 Alternative 2
6371 `S-<TAB>' `C-u <TAB>'
6372 `M-<left>' `C-c C-x l' `<Esc> <left>'
6373 `M-S-<left>'`C-c C-x L'
6374 `M-<right>' `C-c C-x r' `<Esc>
6376 `M-S-<right>'`C-c C-x R'
6377 `M-<up>' `C-c C-x u' `<Esc> <up>'
6378 `M-S-<up>' `C-c C-x U'
6379 `M-<down>' `C-c C-x d' `<Esc> <down>'
6380 `M-S-<down>'`C-c C-x D'
6381 `S-<RET>' `C-c C-x c'
6382 `M-<RET>' `C-c C-x m' `<Esc> <RET>'
6383 `M-S-<RET>' `C-c C-x M'
6384 `S-<left>' `C-c <left>'
6385 `S-<right>' `C-c <right>'
6387 `S-<down>' `C-c <down>'
6388 `C-S-<left>'`C-c C-x
6390 `C-S-<right>'`C-c C-x
6394 File: org, Node: Interaction, Next: Bugs, Prev: TTY keys, Up: Miscellaneous
6396 13.7 Interaction with other packages
6397 ====================================
6399 Org-mode lives in the world of GNU Emacs and interacts in various ways
6400 with other code out there.
6404 * Cooperation:: Packages Org-mode cooperates with
6405 * Conflicts:: Packages that lead to conflicts
6408 File: org, Node: Cooperation, Next: Conflicts, Prev: Interaction, Up: Interaction
6410 13.7.1 Packages that Org-mode cooperates with
6411 ---------------------------------------------
6413 `calc.el' by Dave Gillespie
6414 Org-mode uses the calc package for implementing spreadsheet
6415 functionality in its tables (*note The spreadsheet::). Org-mode
6416 checks for the availability of calc by looking for the function
6417 `calc-eval' which should be autoloaded in your setup if calc has
6418 been installed properly. As of Emacs 22, calc is part of the Emacs
6419 distribution. Another possibility for interaction between the two
6420 packages is using calc for embedded calculations. *Note Embedded
6421 Mode: (calc)Embedded Mode.
6423 `constants.el' by Carsten Dominik
6424 In a table formula (*note The spreadsheet::), it is possible to use
6425 names for natural constants or units. Instead of defining your own
6426 constants in the variable `org-table-formula-constants', install
6427 the `constants' package which defines a large number of constants
6428 and units, and lets you use unit prefixes like `M' for `Mega' etc.
6429 You will need version 2.0 of this package, available at
6430 `http://www.astro.uva.nl/~dominik/Tools'. Org-mode checks for the
6431 function `constants-get', which has to be autoloaded in your
6432 setup. See the installation instructions in the file
6435 `cdlatex.el' by Carsten Dominik
6436 Org-mode can make use of the cdlatex package to efficiently enter
6437 LaTeX fragments into Org-mode files. See *Note CDLaTeX mode::.
6439 `remember.el' by John Wiegley
6440 Org mode cooperates with remember, see *Note Remember::.
6441 `Remember.el' is not part of Emacs, find it on the web.
6443 `table.el' by Takaaki Ota
6444 Complex ASCII tables with automatic line wrapping, column- and
6445 row-spanning, and alignment can be created using the Emacs table
6446 package by Takaaki Ota (`http://sourceforge.net/projects/table',
6447 and also part of Emacs 22). When <TAB> or `C-c C-c' is pressed in
6448 such a table, Org-mode will call `table-recognize-table' and move
6449 the cursor into the table. Inside a table, the keymap of Org-mode
6450 is inactive. In order to execute Org-mode-related commands, leave
6454 Recognize `table.el' table. Works when the cursor is in a
6458 Insert a table.el table. If there is already a table at
6459 point, this command converts it between the table.el format
6460 and the Org-mode format. See the documentation string of the
6461 command `org-convert-table' for the restrictions under which
6463 `table.el' is part of Emacs 22.
6465 `footnote.el' by Steven L. Baur
6466 Org-mode recognizes numerical footnotes as provided by this package
6467 (*note Footnotes::).
6470 File: org, Node: Conflicts, Prev: Cooperation, Up: Interaction
6472 13.7.2 Packages that lead to conflicts with Org-mode
6473 ----------------------------------------------------
6475 `allout.el' by Ken Manheimer
6476 Startup of Org-mode may fail with the error message
6477 `(wrong-type-argument keymapp nil)' when there is an outdated
6478 version `allout.el' on the load path, for example the version
6479 distributed with Emacs 21.x. Upgrade to Emacs 22 and this problem
6480 will disappear. If for some reason you cannot do this, make sure
6481 that org.el is loaded _before_ `allout.el', for example by putting
6482 `(require 'org)' early enough into your `.emacs' file.
6484 `CUA.el' by Kim. F. Storm
6485 Keybindings in Org-mode conflict with the `S-<cursor>' keys used
6486 by CUA-mode (as well as pc-select-mode and s-region-mode) to
6487 select and extend the region. If you want to use one of these
6488 packages along with Org-mode, configure the variable
6489 `org-CUA-compatible'. When set, Org-mode will move the following
6490 keybindings in Org-mode files, and in the agenda buffer (but not
6491 during date selection).
6493 S-UP -> M-p S-DOWN -> M-n
6494 S-LEFT -> M-- S-RIGHT -> M-+
6496 Yes, these are unfortunately more difficult to remember. If you
6497 want to have other replacement keys, look at the variable
6498 `org-disputed-keys'.
6500 `windmove.el' by Hovav Shacham
6501 Also this package uses the `S-<cursor>' keys, so everything written
6502 in the paragraph above about CUA mode also applies here.
6504 `footnote.el' by Steven L. Baur
6505 Org-mode supports the syntax of the footnote package, but only the
6506 numerical footnote markers. Also, the default key for footnote
6507 commands, `C-c !' is already used by Org-mode. You could use the
6508 variable `footnote-prefix' to switch footnotes commands to another
6509 key. Or, you could use `org-replace-disputed-keys' and
6510 `org-disputed-keys' to change the settings in Org-mode.
6514 File: org, Node: Bugs, Prev: Interaction, Up: Miscellaneous
6519 Here is a list of things that should work differently, but which I have
6520 found too hard to fix.
6522 * If a table field starts with a link, and if the corresponding table
6523 column is narrowed (*note Narrow columns::) to a width too small to
6524 display the link, the field would look entirely empty even though
6525 it is not. To prevent this, Org-mode throws an error. The
6526 work-around is to make the column wide enough to fit the link, or
6527 to add some text (at least 2 characters) before the link in the
6530 * Narrowing table columns does not work on XEmacs, because the
6531 `format' function does not transport text properties.
6533 * Text in an entry protected with the `QUOTE' keyword should not
6536 * When the application called by `C-c C-o' to open a file link fails
6537 (for example because the application does not exist or refuses to
6538 open the file), it does so silently. No error message is
6541 * Recalculating a table line applies the formulas from left to right.
6542 If a formula uses _calculated_ fields further down the row,
6543 multiple recalculation may be needed to get all fields consistent.
6544 You may use the command `org-table-iterate' (`C-u C-c *') to
6545 recalculate until convergence.
6547 * A single letter cannot be made bold, for example `*a*'.
6549 * The exporters work well, but could be made more efficient.
6552 File: org, Node: Extensions and Hacking, Next: History and Acknowledgments, Prev: Miscellaneous, Up: Top
6554 Appendix A Extensions, Hooks and Hacking
6555 ****************************************
6557 This appendix lists extensions for Org-mode written by other authors.
6558 It also covers some aspects where users can extend the functionality of
6563 * Extensions:: Existing 3rd-part extensions
6564 * Adding hyperlink types:: New custom link types
6565 * Tables in arbitrary syntax:: Orgtbl for LaTeX and other programs
6566 * Dynamic blocks:: Automatically filled blocks
6567 * Special agenda views:: Customized views
6568 * Using the property API:: Writing programs that use entry properties
6571 File: org, Node: Extensions, Next: Adding hyperlink types, Prev: Extensions and Hacking, Up: Extensions and Hacking
6573 A.1 Third-party extensions for Org-mode
6574 =======================================
6576 The following extensions for Org-mode have been written by other people:
6578 `org-publish.el' by David O'Toole
6579 This package provides facilities for publishing related sets of
6580 Org-mode files together with linked files like images as webpages.
6581 It is highly configurable and can be used for other publishing
6582 purposes as well. As of Org-mode version 4.30, `org-publish.el'
6583 is part of the Org-mode distribution. It is not yet part of
6584 Emacs, however, a delay caused by the preparations for the 22.1
6585 release. In the mean time, `org-publish.el' can be downloaded
6586 from David's site: `http://dto.freeshell.org/e/org-publish.el'.
6588 `org-mouse.el' by Piotr Zielinski
6589 This package implements extended mouse functionality for Org-mode.
6590 It allows you to cycle visibility and to edit the document
6591 structure with the mouse. Best of all, it provides a
6592 context-sensitive menu on <mouse-3> that changes depending on the
6593 context of a mouse-click. As of Org-mode version 4.53,
6594 `org-mouse.el' is part of the Org-mode distribution. It is not
6595 yet part of Emacs, however, a delay caused by the preparations for
6596 the 22.1 release. In the mean time, `org-mouse.el' can be
6597 downloaded from Piotr's site:
6598 `http://www.cl.cam.ac.uk/~pz215/files/org-mouse.el'.
6600 `org-blog.el' by David O'Toole
6601 A blogging plug-in for `org-publish.el'.
6602 `http://dto.freeshell.org/notebook/OrgMode.html'.
6604 `blorg.el' by Bastien Guerry
6605 Publish Org-mode files as blogs.
6606 `http://www.cognition.ens.fr/~guerry/blorg.html'.
6608 `org2rem.el' by Bastien Guerry
6609 Translates Org-mode files into something readable by Remind.
6610 `http://www.cognition.ens.fr/~guerry/u/org2rem.el'.
6613 File: org, Node: Adding hyperlink types, Next: Tables in arbitrary syntax, Prev: Extensions, Up: Extensions and Hacking
6615 A.2 Adding hyperlink types
6616 ==========================
6618 Org-mode has a large number of hyperlink types built-in (*note
6619 Hyperlinks::). If you would like to add new link types, it provides an
6620 interface for doing so. Lets look at an example file `org-man.el' that
6621 will add support for creating links like `[[man:printf][The printf
6622 manpage]]' to show unix manual pages inside emacs:
6624 ;;; org-man.el - Support for links to manpages in Org-mode
6628 (org-add-link-type "man" 'org-man-open)
6629 (add-hook 'org-store-link-functions 'org-man-store-link)
6631 (defcustom org-man-command 'man
6632 "The Emacs command to be used to display a man page."
6634 :type '(choice (const man) (const woman)))
6636 (defun org-man-open (path)
6637 "Visit the manpage on PATH.
6638 PATH should be a topic that can be thrown at the man command."
6639 (funcall org-man-command path))
6641 (defun org-man-store-link ()
6642 "Store a link to a manpage."
6643 (when (memq major-mode '(Man-mode woman-mode))
6644 ;; This is a man page, we do make this link
6645 (let* ((page (org-man-get-page-name))
6646 (link (concat "man:" page))
6647 (description (format "Manpage for %s" page)))
6648 (org-store-link-props
6651 :description description))))
6653 (defun org-man-get-page-name ()
6654 "Extract the page name from the buffer name."
6655 ;; This works for both `Man-mode' and `woman-mode'.
6656 (if (string-match " \\(\\S-+\\)\\*" (buffer-name))
6657 (match-string 1 (buffer-name))
6658 (error "Cannot create link to this man page")))
6662 ;;; org-man.el ends here
6664 You would activate this new link type in `.emacs' with
6668 Lets go through the file and see what it does.
6669 1. It does `(require 'org)' to make sure that `org.el' has been
6672 2. The next line calls `org-add-link-type' to define a new link type
6673 with prefix `man'. The call also contains the name of a function
6674 that will be called to follow such a link.
6676 3. The next line adds a function to `org-store-link-functions', in
6677 order to allow the command `C-c l' to record a useful link in a
6678 buffer displaying a man page.
6680 The rest of the file defines the necessary variables and functions.
6681 First there is a customization variable that determines which emacs
6682 command should be used to display manpages. There are two options,
6683 `man' and `woman'. Then the function to follow a link is defined. It
6684 gets the link path as an argument - in this case the link path is just
6685 a topic for the manual command. The function calls the value of
6686 `org-man-command' to display the man page.
6688 Finally the function `org-man-store-link' is defined. When you try
6689 to store a link with `C-c l', also this function will be called to try
6690 to make a link. The function must first decide if it is supposed to
6691 create the link for this buffer type, we do this by checking the value
6692 of the variable `major-mode'. If not, the function must exit and
6693 retunr the value `nil'. If yes, the link is created by getting the
6694 manual tpoic from the buffer name and prefixing it with the string
6695 `man:'. Then it must call the command `org-store-link-props' and set
6696 the `:type' and `:link' properties. Optionally you can also set the
6697 `:description' property to provide a default for the link description
6698 when the link is later inserted into tan Org-mode buffer with `C-c C-l'.
6701 File: org, Node: Tables in arbitrary syntax, Next: Dynamic blocks, Prev: Adding hyperlink types, Up: Extensions and Hacking
6703 A.3 Tables in arbitrary syntax
6704 ==============================
6706 Since Orgtbl-mode can be used as a minor mode in arbitrary buffers, a
6707 frequent feature request has been to make it work with native tables in
6708 specific languages, for example LaTeX. However, this is extremely hard
6709 to do in a general way, would lead to a customization nightmare, and
6710 would take away much of the simplicity of the Orgtbl-mode table editor.
6712 This appendix describes a different approach. We keep the
6713 Orgtbl-mode table in its native format (the source table), and use a
6714 custom function to translate the table to the correct syntax, and to
6715 install it in the right location (the target table). This puts the
6716 burden of writing conversion functions on the user, but it allows for a
6717 very flexible system.
6721 * Radio tables:: Sending and receiving
6722 * A LaTeX example:: Step by step, almost a tutorial
6723 * Translator functions:: Copy and modify
6726 File: org, Node: Radio tables, Next: A LaTeX example, Prev: Tables in arbitrary syntax, Up: Tables in arbitrary syntax
6731 To define the location of the target table, you first need to create two
6732 lines that are comments in the current mode, but contain magic words for
6733 Orgtbl-mode to find. Orgtbl-mode will insert the translated table
6734 between these lines, replacing whatever was there before. For example:
6736 /* BEGIN RECEIVE ORGTBL table_name */
6737 /* END RECEIVE ORGTBL table_name */
6739 Just above the source table, we put a special line that tells
6740 Orgtbl-mode how to translate this table and where to install it. For
6742 #+ORGTBL: SEND table_name translation_function arguments....
6744 `table_name' is the reference name for the table that is also used in
6745 the receiver lines. `translation_function' is the Lisp function that
6746 does the translation. Furthermore, the line can contain a list of
6747 arguments (alternating key and value) at the end. The arguments will be
6748 passed as a property list to the translation function for
6749 interpretation. A few standard parameters are already recognized and
6750 acted upon before the translation function is called:
6753 Skip the first N lines of the table. Hlines do count!
6755 `:skipcols (n1 n2 ...)'
6756 List of columns that should be skipped. If the table has a column
6757 with calculation marks, that column is automatically discarded as
6758 well. Please note that the translator function sees the table
6759 _after_ the removal of these columns, the function never knows
6760 that there have been additional columns.
6762 The one problem remaining is how to keep the source table in the buffer
6763 without disturbing the normal workings of the file, for example during
6764 compilation of a C file or processing of a LaTeX file. There are a
6765 number of different solutions:
6767 * The table could be placed in a block comment if that is supported
6768 by the language. For example, in C-mode you could wrap the table
6769 between `/*' and `*/' lines.
6771 * Sometimes it is possible to put the table after some kind of END
6772 statement, for example `\bye' in TeX and `\end{document}' in LaTeX.
6774 * You can just comment the table line by line whenever you want to
6775 process the file, and uncomment it whenever you need to edit the
6776 table. This only sounds tedious - the command `M-x
6777 orgtbl-toggle-comment' does make this comment-toggling very easy,
6778 in particular if you bind it to a key.
6781 File: org, Node: A LaTeX example, Next: Translator functions, Prev: Radio tables, Up: Tables in arbitrary syntax
6783 A.3.2 A LaTeX example
6784 ---------------------
6786 The best way to wrap the source table in LaTeX is to use the `comment'
6787 environment provided by `comment.sty'. It has to be activated by
6788 placing `\usepackage{comment}' into the document header. Orgtbl-mode
6789 can insert a radio table skeleton(1) with the command `M-x
6790 orgtbl-insert-radio-table'. You will be prompted for a table name,
6791 lets say we use `salesfigures'. You will then get the following
6794 % BEGIN RECEIVE ORGTBL salesfigures
6795 % END RECEIVE ORGTBL salesfigures
6797 #+ORGTBL: SEND salesfigures orgtbl-to-latex
6801 The `#+ORGTBL: SEND' line tells orgtbl-mode to use the function
6802 `orgtbl-to-latex' to convert the table into LaTeX and to put it into
6803 the receiver location with name `salesfigures'. You may now fill in
6804 the table, feel free to use the spreadsheet features(2):
6806 % BEGIN RECEIVE ORGTBL salesfigures
6807 % END RECEIVE ORGTBL salesfigures
6809 #+ORGTBL: SEND salesfigures orgtbl-to-latex
6810 | Month | Days | Nr sold | per day |
6811 |-------+------+---------+---------|
6812 | Jan | 23 | 55 | 2.4 |
6813 | Feb | 21 | 16 | 0.8 |
6814 | March | 22 | 278 | 12.6 |
6815 #+TBLFM: $4=$3/$2;%.1f
6816 % $ (optional extra dollar to keep font-lock happy, see footnote)
6819 When you are done, press `C-c C-c' in the table to get the converted
6820 table inserted between the two marker lines.
6822 Now lets assume you want to make the table header by hand, because
6823 you want to control how columns are aligned etc. In this case we make
6824 sure that the table translator does skip the first 2 lines of the source
6825 table, and tell the command to work as a splice, i.e. to not produce
6826 header and footer commands of the target table:
6828 \begin{tabular}{lrrr}
6829 Month & \multicolumn{1}{c}{Days} & Nr.\ sold & per day\\
6830 % BEGIN RECEIVE ORGTBL salesfigures
6831 % END RECEIVE ORGTBL salesfigures
6835 #+ORGTBL: SEND salesfigures orgtbl-to-latex :splice t :skip 2
6836 | Month | Days | Nr sold | per day |
6837 |-------+------+---------+---------|
6838 | Jan | 23 | 55 | 2.4 |
6839 | Feb | 21 | 16 | 0.8 |
6840 | March | 22 | 278 | 12.6 |
6841 #+TBLFM: $4=$3/$2;%.1f
6844 The LaTeX translator function `orgtbl-to-latex' is already part of
6845 Orgtbl-mode. It uses a `tabular' environment to typeset the table and
6846 marks horizontal lines with `\hline'. Furthermore, it interprets the
6847 following parameters:
6850 When set to t, return only table body lines, don't wrap them into a
6851 tabular environment. Default is nil.
6854 A format to be used to wrap each field, should contain `%s' for the
6855 original field value. For example, to wrap each field value in
6856 dollars, you could use `:fmt "$%s$"'. This may also be a property
6857 list with column numbers and formats. for example `:fmt (2 "$%s$"
6861 Use this format to print numbers with exponentials. The format
6862 should have `%s' twice for inserting mantissa and exponent, for
6863 example `"%s\\times10^{%s}"'. The default is `"%s\\,(%s)"'. This
6864 may also be a property list with column numbers and formats, for
6865 example `:efmt (2 "$%s\\times10^{%s}$" 4 "$%s\\cdot10^{%s}$")'.
6866 After `efmt' has been applied to a value, `fmt' will also be
6869 ---------- Footnotes ----------
6871 (1) By default this works only for LaTeX, HTML, and TeXInfo.
6872 Configure the variable `orgtbl-radio-tables' to install templates for
6875 (2) If the `#+TBLFM' line contains an odd number of dollar
6876 characters, this may cause problems with font-lock in latex-mode. As
6877 shown in the example you can fix this by adding an extra line inside the
6878 `comment' environment that is used to balance the dollar expressions.
6879 If you are using AUCTeX with the font-latex library, a much better
6880 solution is to add the `comment' environment to the variable
6881 `LaTeX-verbatim-environments'.
6884 File: org, Node: Translator functions, Prev: A LaTeX example, Up: Tables in arbitrary syntax
6886 A.3.3 Translator functions
6887 --------------------------
6889 Orgtbl-mode has several translator functions built-in:
6890 `orgtbl-to-latex', `orgtbl-to-html', and `orgtbl-to-texinfo'. Except
6891 for `orgtbl-to-html'(1), these all use a generic translator,
6892 `orgtbl-to-generic'. For example, `orgtbl-to-latex' itself is a very
6893 short function that computes the column definitions for the `tabular'
6894 environment, defines a few field and line separators and then hands
6895 over to the generic translator. Here is the entire code:
6897 (defun orgtbl-to-latex (table params)
6898 "Convert the orgtbl-mode TABLE to LaTeX."
6899 (let* ((alignment (mapconcat (lambda (x) (if x "r" "l"))
6900 org-table-last-alignment ""))
6903 :tstart (concat "\\begin{tabular}{" alignment "}")
6904 :tend "\\end{tabular}"
6905 :lstart "" :lend " \\\\" :sep " & "
6906 :efmt "%s\\,(%s)" :hline "\\hline")))
6907 (orgtbl-to-generic table (org-combine-plists params2 params))))
6909 As you can see, the properties passed into the function (variable
6910 PARAMS) are combined with the ones newly defined in the function
6911 (variable PARAMS2). The ones passed into the function (i.e. the ones
6912 set by the `ORGTBL SEND' line) take precedence. So if you would like
6913 to use the LaTeX translator, but wanted the line endings to be
6914 `\\[2mm]' instead of the default `\\', you could just overrule the
6917 #+ORGTBL: SEND test orgtbl-to-latex :lend " \\\\[2mm]"
6919 For a new language, you can either write your own converter function
6920 in analogy with the LaTeX translator, or you can use the generic
6921 function directly. For example, if you have a language where a table
6922 is started with `!BTBL!', ended with `!ETBL!', and where table lines are
6923 started with `!BL!', ended with `!EL!' and where the field separator is
6924 a TAB, you could call the generic translator like this (on a single
6927 #+ORGTBL: SEND test orgtbl-to-generic :tstart "!BTBL!" :tend "!ETBL!"
6928 :lstart "!BL! " :lend " !EL!" :sep "\t"
6930 Please check the documentation string of the function
6931 `orgtbl-to-generic' for a full list of parameters understood by that
6932 function and remember that you can pass each of them into
6933 `orgtbl-to-latex', `orgtbl-to-texinfo', and any other function using
6934 the generic function.
6936 Of course you can also write a completely new function doing
6937 complicated things the generic translator cannot do. A translator
6938 function takes two arguments. The first argument is the table, a list
6939 of lines, each line either the symbol `hline' or a list of fields. The
6940 second argument is the property list containing all parameters
6941 specified in the `#+ORGTBL: SEND' line. The function must return a
6942 single string containing the formatted table. If you write a generally
6943 useful translator, please post it on `emacs-orgmode@gnu.org' so that
6944 others can benefit from your work.
6946 ---------- Footnotes ----------
6948 (1) The HTML translator uses the same code that produces tables
6952 File: org, Node: Dynamic blocks, Next: Special agenda views, Prev: Tables in arbitrary syntax, Up: Extensions and Hacking
6957 Org-mode documents can contain _dynamic blocks_. These are specially
6958 marked regions that are updated by some user-written function. A good
6959 example for such a block is the clock table inserted by the command
6960 `C-c C-x C-r' (*note Clocking work time::).
6962 Dynamic block are enclosed by a BEGIN-END structure that assigns a
6963 name to the block and can also specify parameters for the function
6964 producing the content of the block.
6966 #+BEGIN: myblock :parameter1 value1 :parameter2 value2 ...
6970 Dynamic blocks are updated with the following commands
6973 Update dynamic block at point.
6976 Update all dynamic blocks in the current file.
6978 Updating a dynamic block means to remove all the text between BEGIN
6979 and END, parse the BEGIN line for parameters and then call the specific
6980 writer function for this block to insert the new content. For a block
6981 with name `myblock', the writer function is `org-dblock-write:myblock'
6982 with as only parameter a property list with the parameters given in the
6983 begin line. Here is a trivial example of a block that keeps track of
6984 when the block update function was last run:
6986 #+BEGIN: block-update-time :format "on %m/%d/%Y at %H:%M"
6990 The corresponding block writer function could look like this:
6992 (defun org-dblock-write:block-update-time (params)
6993 (let ((fmt (or (plist-get params :format) "%d. %m. %Y")))
6994 (insert "Last block update at: "
6995 (format-time-string fmt (current-time)))))
6997 If you want to make sure that all dynamic blocks are always
6998 up-to-date, you could add the function `org-update-all-dblocks' to a
6999 hook, for example `before-save-hook'. `org-update-all-dblocks' is
7000 written in a way that is does nothing in buffers that are not in
7004 File: org, Node: Special agenda views, Next: Using the property API, Prev: Dynamic blocks, Up: Extensions and Hacking
7006 A.5 Special Agenda Views
7007 ========================
7009 Org-mode provides a special hook that can be used to narrow down the
7010 selection made by any of the agenda views. You may specify a function
7011 that is used at each match to verify if the match should indeed be part
7012 of the agenda view, and if not, how much should be skipped.
7014 Let's say you want to produce a list of projects that contain a
7015 WAITING tag anywhere in the project tree. Let's further assume that
7016 you have marked all tree headings that define a project with the todo
7017 keyword PROJECT. In this case you would run a todo search for the
7018 keyword PROJECT, but skip the match unless there is a WAITING tag
7019 anywhere in the subtree belonging to the project line.
7021 To achieve this, you must write a function that searches the subtree
7022 for the tag. If the tag is found, the function must return `nil' to
7023 indicate that this match should not be skipped. If there is no such
7024 tag, return the location of the end of the subtree, to indicate that
7025 search should continue from there.
7027 (defun my-skip-unless-waiting ()
7028 "Skip trees that are not waiting"
7029 (let ((subtree-end (save-excursion (org-end-of-subtree t))))
7030 (if (re-search-forward ":WAITING:" subtree-end t)
7031 nil ; tag found, do not skip
7032 subtree-end))) ; tag not found, continue after end of subtree
7034 Now you may use this function in an agenda custom command, for
7037 (org-add-agenda-custom-command
7038 '("b" todo "PROJECT"
7039 ((org-agenda-skip-function 'my-org-waiting-projects)
7040 (org-agenda-overriding-header "Projects waiting for something: "))))
7042 Note that this also binds `org-agenda-overriding-header' to get a
7043 meaningful header in the agenda view.
7045 You may also put a Lisp form into `org-agenda-skip-function'. In
7046 particular, you may use the functions `org-agenda-skip-entry-if' and
7047 `org-agenda-skip-subtree-if' in this form, for example:
7049 `'(org-agenda-skip-entry-if 'scheduled)'
7050 Skip current entry if it has been scheduled.
7052 `'(org-agenda-skip-entry-if 'notscheduled)'
7053 Skip current entry if it has not been scheduled.
7055 `'(org-agenda-skip-entry-if 'deadline)'
7056 Skip current entry if it has a deadline.
7058 `'(org-agenda-skip-entry-if 'scheduled 'deadline)'
7059 Skip current entry if it has a deadline, or if it is scheduled.
7061 `'(org-agenda-skip-entry 'regexp "regular expression")'
7062 Skip current entry if the regular expression contained in the
7063 variable `org-agenda-skip-regexp' matches in the entry.
7065 `'(org-agenda-skip-subtree-if 'regexp "regular expression")'
7066 Same as above, but check and skip the entire subtree.
7068 Therefore we could also have written the search for WAITING projects
7069 like this, even without defining a special function:
7071 (org-add-agenda-custom-command
7072 '("b" todo "PROJECT"
7073 ((org-agenda-skip-function '(org-agenda-skip-subtree-if
7074 'regexp ":WAITING:"))
7075 (org-agenda-overriding-header "Projects waiting for something: "))))
7078 File: org, Node: Using the property API, Prev: Special agenda views, Up: Extensions and Hacking
7080 A.6 Using the property API
7081 ==========================
7083 Here is a description of the functions that can be used to work with
7086 -- Function: org-entry-properties &optional pom which
7087 Get all properties of the entry at point-or-marker POM. This
7088 includes the TODO keyword, the tags, time strings for deadline,
7089 scheduled, and clocking, and any additional properties defined in
7090 the entry. The return value is an alist, keys may occur multiple
7091 times if the property key was used several times. POM may also be
7092 nil, in which case the current entry is used. If WHICH is nil or
7093 `all', get all properties. If WHICH is `special' or `standard',
7094 only get that subclass.
7096 -- Function: org-entry-get pom property &optional inherit
7097 Get value of PROPERTY for entry at point-or-marker POM. If
7098 INHERIT is non-nil and the entry does not have the property, then
7099 also check higher levels of the hierarchy.
7101 -- Function: org-entry-delete pom property
7102 Delete the property PROPERTY from entry at point-or-marker POM.
7104 -- Function: org-entry-put pom property value
7105 Set PROPERTY to VALUE for entry at point-or-marker POM.
7107 -- Function: org-buffer-property-keys &optional include-specials
7108 Get all property keys in the current buffer.
7110 -- Function: org-insert-property-drawer
7111 Insert a property drawer at point.
7114 File: org, Node: History and Acknowledgments, Next: Index, Prev: Extensions and Hacking, Up: Top
7116 Appendix B History and Acknowledgments
7117 **************************************
7119 Org-mode was borne in 2003, out of frustration over the user interface
7120 of the Emacs outline-mode. I was trying to organize my notes and
7121 projects, and using Emacs seemed to be the natural way to go. However,
7122 having to remember eleven different commands with two or three keys per
7123 command, only to hide and unhide parts of the outline tree, that seemed
7124 entirely unacceptable to me. Also, when using outlines to take notes, I
7125 constantly want to restructure the tree, organizing it parallel to my
7126 thoughts and plans. _Visibility cycling_ and _structure editing_ were
7127 originally implemented in the package `outline-magic.el', but quickly
7128 moved to the more general `org.el'. As this environment became
7129 comfortable for project planning, the next step was adding _TODO
7130 entries_, basic _time stamps_, and _table support_. These areas
7131 highlight the two main goals that Org-mode still has today: To create a
7132 new, outline-based, plain text mode with innovative and intuitive
7133 editing features, and to incorporate project planning functionality
7134 directly into a notes file.
7136 Since the first release, literally thousands of emails to me or on
7137 `emacs-orgmode@gnu.org' have provided a constant stream of bug reports,
7138 feedback, new ideas, and sometimes patches and add-on code. Many
7139 thanks to everyone who has helped to improve this package. I am trying
7140 to keep here a list of the people who had significant influence in
7141 shaping one or more aspects of Org-mode. The list may not be complete,
7142 if I have forgotten someone, please accept my apologies and let me know.
7144 * Russel Adams came up with the idea for drawers.
7146 * Thomas Baumann contributed the code for links to the MH-E email
7149 * Alex Bochannek provided a patch for rounding time stamps.
7151 * Charles Cave's suggestion sparked the implementation of templates
7154 * Pavel Chalmoviansky influenced the agenda treatment of items with
7157 * Gregory Chernov patched support for lisp forms into table
7158 calculations and improved XEmacs compatibility, in particular by
7159 porting `nouline.el' to XEmacs.
7161 * Sacha Chua suggested to copy some linking code from Planner.
7163 * Eddward DeVilla proposed and tested checkbox statistics. He also
7164 came up with the idea of properties, and that there should be an
7167 * Kees Dullemond used to edit projects lists directly in HTML and so
7168 inspired some of the early development, including HTML export. He
7169 also asked for a way to narrow wide table columns.
7171 * Christian Egli converted the documentation into TeXInfo format,
7172 patched CSS formatting into the HTML exporter, and inspired the
7175 * David Emery provided a patch for custom CSS support in exported
7178 * Nic Ferrier contributed mailcap and XOXO support.
7180 * John Foerch figured out how to make incremental search show context
7181 around a match in a hidden outline tree.
7183 * Niels Giessen had the idea to automatically archive DONE trees.
7185 * Bastien Guerry wrote the LaTeX exporter and has been prolific with
7186 patches, ideas, and bug reports. to Org-mode.
7188 * Kai Grossjohann pointed out key-binding conflicts with other
7191 * Scott Jaderholm proposed footnotes, control over whitespace between
7192 folded entries, and column view for properties.
7194 * Shidai Liu ("Leo") asked for embedded LaTeX and tested it. He also
7195 provided frequent feedback and some patches.
7197 * Jason F. McBrayer suggested agenda export to CSV format.
7199 * Dmitri Minaev sent a patch to set priority limits on a per-file
7202 * Stefan Monnier provided a patch to keep the Emacs-Lisp compiler
7205 * Rick Moynihan proposed to allow multiple TODO sequences in a file.
7207 * Todd Neal provided patches for links to Info files and elisp forms.
7209 * Tim O'Callaghan suggested in-file links, search options for general
7210 file links, and TAGS.
7212 * Takeshi Okano translated the manual and David O'Toole's tutorial
7215 * Oliver Oppitz suggested multi-state TODO items.
7217 * Scott Otterson sparked the introduction of descriptive text for
7218 links, among other things.
7220 * Pete Phillips helped during the development of the TAGS feature,
7221 and provided frequent feedback.
7223 * T.V. Raman reported bugs and suggested improvements.
7225 * Matthias Rempe (Oelde) provided ideas, Windows support, and quality
7228 * Kevin Rogers contributed code to access VM files on remote hosts.
7230 * Frank Ruell solved the mystery of the `keymapp nil' bug, a
7231 conflict with `allout.el'.
7233 * Jason Riedy sent a patch to fix a bug with export of TODO keywords.
7235 * Philip Rooke created the Org-mode reference card and provided lots
7238 * Christian Schlauer proposed angular brackets around links, among
7241 * Linking to VM/BBDB/GNUS was inspired by Tom Shannon's
7242 `organizer-mode.el'.
7244 * Daniel Sinder came up with the idea of internal archiving by
7247 * Dale Smith proposed link abbreviations.
7249 * Adam Spiers asked for global linking commands and inspired the link
7250 extension system. support mairix.
7252 * David O'Toole wrote `org-publish.el' and drafted the manual
7253 chapter about publishing.
7255 * Ju"rgen Vollmer contributed code generating the table of contents
7258 * Chris Wallace provided a patch implementing the `QUOTE' keyword.
7260 * David Wainberg suggested archiving, and improvements to the linking
7263 * John Wiegley wrote `emacs-wiki.el' and `planner.el'. The
7264 development of Org-mode was fully independent, and both systems are
7265 really different beasts in their basic ideas and implementation
7266 details. I later looked at John's code, however, and learned from
7267 his implementation of (i) links where the link itself is hidden
7268 and only a description is shown, and (ii) popping up a calendar to
7269 select a date. John has also contributed a number of great ideas
7270 directly to Org-mode.
7272 * Carsten Wimmer suggested some changes and helped fix a bug in
7275 * Roland Winkler requested additional keybindings to make Org-mode
7278 * Piotr Zielinski wrote `org-mouse.el', proposed agenda blocks and
7279 contributed various ideas and code snippets.
7282 File: org, Node: Index, Next: Key Index, Prev: History and Acknowledgments, Up: Top
7290 * abbreviation, links: Link abbreviations. (line 6)
7291 * acknowledgments: History and Acknowledgments.
7293 * action, for publishing: Publishing action. (line 6)
7294 * activation: Activation. (line 6)
7295 * active region <1>: HTML Export commands.
7297 * active region <2>: ASCII export. (line 9)
7298 * active region <3>: Built-in table editor.
7300 * active region: Structure editing. (line 64)
7301 * agenda: Weekly/Daily agenda. (line 6)
7302 * agenda dispatcher: Agenda dispatcher. (line 6)
7303 * agenda files: Agenda files. (line 6)
7304 * agenda files, removing buffers: Agenda commands. (line 239)
7305 * agenda views: Agenda views. (line 6)
7306 * agenda views, custom: Custom agenda views. (line 6)
7307 * agenda views, exporting <1>: Exporting Agenda Views.
7309 * agenda views, exporting: Agenda commands. (line 228)
7310 * agenda views, user-defined: Special agenda views.
7312 * agenda, pipe: Extracting Agenda Information for other programs.
7314 * agenda, with block views: Block agenda. (line 6)
7315 * align, STARTUP keyword: In-buffer settings. (line 68)
7316 * allout.el: Conflicts. (line 6)
7317 * angular brackets, around links: External links. (line 43)
7318 * API, for properties <1>: Using the property API.
7320 * API, for properties: Property API. (line 6)
7321 * archive locations: Moving subtrees. (line 23)
7322 * archiving: Archiving. (line 6)
7323 * ASCII export: ASCII export. (line 6)
7324 * author: Feedback. (line 6)
7325 * author info, in export: Export options. (line 25)
7326 * autoload: Activation. (line 6)
7327 * backtrace of an error: Feedback. (line 27)
7328 * BBDB links: External links. (line 6)
7329 * block agenda: Block agenda. (line 6)
7330 * blorg.el: Extensions. (line 32)
7331 * bold text: Enhancing text. (line 15)
7332 * Boolean logic, for tag searches: Tag searches. (line 23)
7333 * bug reports: Feedback. (line 6)
7334 * bugs: Bugs. (line 6)
7335 * C-c C-c, overview: The very busy C-c C-c key.
7337 * calc package: The spreadsheet. (line 6)
7338 * calc.el: Cooperation. (line 6)
7339 * calculations, in tables <1>: The spreadsheet. (line 6)
7340 * calculations, in tables: Built-in table editor.
7342 * calendar commands, from agenda: Agenda commands. (line 191)
7343 * calendar integration: Weekly/Daily agenda. (line 24)
7344 * calendar, for selecting date: The date/time prompt.
7346 * category: Categories. (line 6)
7347 * CDLaTeX: CDLaTeX mode. (line 6)
7348 * cdlatex.el: Cooperation. (line 29)
7349 * checkbox statistics: Checkboxes. (line 23)
7350 * checkboxes: Checkboxes. (line 6)
7351 * children, subtree visibility state: Visibility cycling. (line 10)
7352 * clean outline view: Clean view. (line 6)
7353 * column formula: Column formulas. (line 6)
7354 * column view, for properties: Defining columns. (line 6)
7355 * commands, in agenda buffer: Agenda commands. (line 6)
7356 * comment lines: Comment lines. (line 6)
7357 * completion, of dictionary words: Completion. (line 6)
7358 * completion, of file names: Handling links. (line 43)
7359 * completion, of link abbreviations: Completion. (line 6)
7360 * completion, of links: Handling links. (line 25)
7361 * completion, of option keywords <1>: Completion. (line 6)
7362 * completion, of option keywords <2>: Export options. (line 6)
7363 * completion, of option keywords: Per file keywords. (line 23)
7364 * completion, of property keys: Completion. (line 6)
7365 * completion, of tags <1>: Completion. (line 6)
7366 * completion, of tags: Setting tags. (line 11)
7367 * completion, of TeX symbols: Completion. (line 6)
7368 * completion, of TODO keywords <1>: Completion. (line 6)
7369 * completion, of TODO keywords: Workflow states. (line 15)
7370 * constants, in calculations: References. (line 82)
7371 * constants.el: Cooperation. (line 14)
7372 * constcgs, STARTUP keyword: In-buffer settings. (line 93)
7373 * constSI, STARTUP keyword: In-buffer settings. (line 93)
7374 * content, STARTUP keyword: In-buffer settings. (line 61)
7375 * contents, global visibility state: Visibility cycling. (line 22)
7376 * copying, of subtrees: Structure editing. (line 6)
7377 * creating timestamps: Creating timestamps. (line 6)
7378 * CUA.el: Conflicts. (line 15)
7379 * custom agenda views: Custom agenda views. (line 6)
7380 * custom date/time format: Custom time format. (line 6)
7381 * custom search strings: Custom searches. (line 6)
7382 * customization: Customization. (line 6)
7383 * customtime, STARTUP keyword: In-buffer settings. (line 90)
7384 * cutting, of subtrees: Structure editing. (line 6)
7385 * cycling, of TODO states: TODO basics. (line 13)
7386 * cycling, visibility: Visibility cycling. (line 6)
7387 * daily agenda: Weekly/Daily agenda. (line 6)
7388 * date format, custom: Custom time format. (line 6)
7389 * date range: Time stamps. (line 41)
7390 * date stamps <1>: Time stamps. (line 6)
7391 * date stamps: Timestamps. (line 6)
7392 * date, reading in minibuffer: The date/time prompt.
7394 * DEADLINE keyword: Deadlines and scheduling.
7396 * deadlines: Time stamps. (line 6)
7397 * debugging, of table formulas: Editing and debugging formulas.
7399 * demotion, of subtrees: Structure editing. (line 6)
7400 * diary entries, creating from agenda: Agenda commands. (line 196)
7401 * diary integration: Weekly/Daily agenda. (line 24)
7402 * dictionary word completion: Completion. (line 6)
7403 * directories, for publishing: Sources and destinations.
7405 * dispatching agenda commands: Agenda dispatcher. (line 6)
7406 * display changing, in agenda: Agenda commands. (line 65)
7407 * document structure: Document structure. (line 6)
7408 * DONE, final TODO keyword: Per file keywords. (line 26)
7409 * drawer, for properties: Property syntax. (line 6)
7410 * drawers: Drawers. (line 6)
7411 * dynamic blocks: Dynamic blocks. (line 6)
7412 * editing tables: Tables. (line 6)
7413 * editing, of table formulas: Editing and debugging formulas.
7415 * elisp links: External links. (line 6)
7416 * emphasized text: Export options. (line 25)
7417 * enhancing text: Enhancing text. (line 6)
7418 * evaluate time range: Creating timestamps. (line 48)
7419 * even, STARTUP keyword: In-buffer settings. (line 83)
7420 * exporting: Exporting. (line 6)
7421 * exporting agenda views <1>: Exporting Agenda Views.
7423 * exporting agenda views: Agenda commands. (line 228)
7424 * exporting, not: Comment lines. (line 6)
7425 * extended TODO keywords: TODO extensions. (line 6)
7426 * extension, third-party: Extensions. (line 6)
7427 * external archiving: Moving subtrees. (line 6)
7428 * external links: External links. (line 6)
7429 * external links, in HTML export: Links. (line 6)
7430 * FAQ: Summary. (line 56)
7431 * feedback: Feedback. (line 6)
7432 * field formula: Field formulas. (line 6)
7433 * field references: References. (line 15)
7434 * file links: External links. (line 6)
7435 * file links, searching: Search options. (line 6)
7436 * file name completion: Handling links. (line 43)
7437 * files for agenda: Agenda files. (line 6)
7438 * files, adding to agenda list: Agenda files. (line 12)
7439 * files, selecting for publishing: Selecting files. (line 6)
7440 * fixed width: Enhancing text. (line 28)
7441 * fixed-width sections: Export options. (line 25)
7442 * folded, subtree visibility state: Visibility cycling. (line 10)
7443 * folding, sparse trees: Sparse trees. (line 6)
7444 * following links: Handling links. (line 58)
7445 * footnote.el <1>: Conflicts. (line 35)
7446 * footnote.el <2>: Cooperation. (line 56)
7447 * footnote.el: Footnotes. (line 6)
7448 * footnotes <1>: Export options. (line 25)
7449 * footnotes: Footnotes. (line 6)
7450 * format specifier: Formula syntax for Calc.
7452 * format, of links: Link format. (line 6)
7453 * formula debugging: Editing and debugging formulas.
7455 * formula editing: Editing and debugging formulas.
7457 * formula syntax, Calc: Formula syntax for Calc.
7459 * formula, for individual table field: Field formulas. (line 6)
7460 * formula, for table column: Column formulas. (line 6)
7461 * formula, in tables: Built-in table editor.
7463 * global cycling: Visibility cycling. (line 22)
7464 * global keybindings: Activation. (line 6)
7465 * global TODO list: Global TODO list. (line 6)
7466 * global visibility states: Visibility cycling. (line 22)
7467 * GNUS links: External links. (line 6)
7468 * grouping columns in tables: Column groups. (line 6)
7469 * hand-formatted lists: Enhancing text. (line 11)
7470 * headline levels: Export options. (line 25)
7471 * headline levels, for exporting <1>: LaTeX export commands.
7473 * headline levels, for exporting <2>: HTML Export commands.
7475 * headline levels, for exporting: ASCII export. (line 21)
7476 * headline navigation: Motion. (line 6)
7477 * headline tagging: Tags. (line 6)
7478 * headline, promotion and demotion: Structure editing. (line 6)
7479 * headlines: Headlines. (line 6)
7480 * hide text: Visibility cycling. (line 6)
7481 * hidestars, STARTUP keyword: In-buffer settings. (line 83)
7482 * hiding leading stars: Clean view. (line 6)
7483 * history: History and Acknowledgments.
7485 * horizontal rules, in exported files: Enhancing text. (line 18)
7486 * HTML export: HTML export. (line 6)
7487 * HTML, and orgtbl-mode: Translator functions.
7489 * hyperlinks: Hyperlinks. (line 6)
7490 * hyperlinks, adding new types: Adding hyperlink types.
7492 * iCalendar export: iCalendar export. (line 6)
7493 * images, inline in HTML: Images. (line 6)
7494 * in-buffer settings: In-buffer settings. (line 6)
7495 * inactive timestamp: Time stamps. (line 50)
7496 * index, of published pages: Project page index. (line 6)
7497 * Info links: External links. (line 6)
7498 * inheritance, of tags: Tag inheritance. (line 6)
7499 * inlining images in HTML: Images. (line 6)
7500 * inserting links: Handling links. (line 25)
7501 * installation: Installation. (line 6)
7502 * internal archiving: ARCHIVE tag. (line 6)
7503 * internal links: Internal links. (line 6)
7504 * internal links, in HTML export: Links. (line 6)
7505 * introduction: Introduction. (line 6)
7506 * italic text: Enhancing text. (line 15)
7507 * jumping, to headlines: Motion. (line 6)
7508 * keybindings, global: Activation. (line 6)
7509 * keyword options: Per file keywords. (line 6)
7510 * LaTeX export: LaTeX export. (line 6)
7511 * LaTeX fragments <1>: Export options. (line 25)
7512 * LaTeX fragments: LaTeX fragments. (line 6)
7513 * LaTeX fragments, export: Enhancing text. (line 21)
7514 * LaTeX fragments, preview: Processing LaTeX fragments.
7516 * LaTeX interpretation: Embedded LaTeX. (line 6)
7517 * LaTeX, and orgtbl-mode: A LaTeX example. (line 6)
7518 * level, require for tags match: Tag searches. (line 68)
7519 * linebreak preservation: Export options. (line 25)
7520 * linebreak, forced: Enhancing text. (line 35)
7521 * link abbreviations: Link abbreviations. (line 6)
7522 * link abbreviations, completion of: Completion. (line 6)
7523 * link completion: Handling links. (line 25)
7524 * link format: Link format. (line 6)
7525 * links, external: External links. (line 6)
7526 * links, finding next/previous: Handling links. (line 91)
7527 * links, handling: Handling links. (line 6)
7528 * links, in HTML export: Links. (line 6)
7529 * links, internal: Internal links. (line 6)
7530 * links, publishing: Publishing links. (line 6)
7531 * links, radio targets: Radio targets. (line 6)
7532 * links, returning to: Handling links. (line 85)
7533 * Lisp forms, as table formulas: Formula syntax for Lisp.
7535 * lists, hand-formatted: Enhancing text. (line 11)
7536 * lists, ordered: Plain lists. (line 6)
7537 * lists, plain: Plain lists. (line 6)
7538 * logdone, STARTUP keyword: In-buffer settings. (line 72)
7539 * logging, of progress: Progress logging. (line 6)
7540 * lognoteclock-out, STARTUP keyword: In-buffer settings. (line 72)
7541 * lognotedone, STARTUP keyword: In-buffer settings. (line 72)
7542 * lognotestate, STARTUP keyword: In-buffer settings. (line 72)
7543 * logrepeat, STARTUP keyword: In-buffer settings. (line 72)
7544 * maintainer: Feedback. (line 6)
7545 * mark ring: Handling links. (line 81)
7546 * marking characters, tables: Advanced features. (line 40)
7547 * matching, of properties: Matching tags and properties.
7549 * matching, of tags: Matching tags and properties.
7551 * matching, tags: Tags. (line 6)
7552 * math symbols: Math symbols. (line 6)
7553 * MH-E links: External links. (line 6)
7554 * minor mode for structure editing: orgstruct-mode. (line 6)
7555 * minor mode for tables: orgtbl-mode. (line 6)
7556 * mode, for calc: Formula syntax for Calc.
7558 * motion commands in agenda: Agenda commands. (line 19)
7559 * motion, between headlines: Motion. (line 6)
7560 * name, of column or field: References. (line 82)
7561 * named references: References. (line 82)
7562 * names as TODO keywords: TODO types. (line 6)
7563 * narrow columns in tables: Narrow columns. (line 6)
7564 * noalign, STARTUP keyword: In-buffer settings. (line 68)
7565 * nologging, STARTUP keyword: In-buffer settings. (line 72)
7566 * nologrepeat, STARTUP keyword: In-buffer settings. (line 72)
7567 * occur, command: Sparse trees. (line 6)
7568 * odd, STARTUP keyword: In-buffer settings. (line 83)
7569 * option keyword completion: Completion. (line 6)
7570 * options, for custom agenda views: Setting Options. (line 6)
7571 * options, for customization: Customization. (line 6)
7572 * options, for export: Export options. (line 6)
7573 * options, for publishing: Publishing options. (line 6)
7574 * ordered lists: Plain lists. (line 6)
7575 * org-agenda, command: Weekly/Daily agenda. (line 9)
7576 * org-blog.el: Extensions. (line 28)
7577 * org-mode, turning on: Activation. (line 22)
7578 * org-mouse.el: Extensions. (line 16)
7579 * org-publish-project-alist: Project alist. (line 6)
7580 * org-publish.el: Extensions. (line 8)
7581 * org2rem.el: Extensions. (line 36)
7582 * orgstruct-mode: orgstruct-mode. (line 6)
7583 * orgtbl-mode <1>: Tables in arbitrary syntax.
7585 * orgtbl-mode: orgtbl-mode. (line 6)
7586 * outline tree: Headlines. (line 6)
7587 * outline-mode: Outlines. (line 6)
7588 * outlines: Outlines. (line 6)
7589 * overview, global visibility state: Visibility cycling. (line 22)
7590 * overview, STARTUP keyword: In-buffer settings. (line 61)
7591 * packages, interaction with other: Interaction. (line 6)
7592 * pasting, of subtrees: Structure editing. (line 6)
7593 * per file keywords: Per file keywords. (line 6)
7594 * plain lists: Plain lists. (line 6)
7595 * plain text external links: External links. (line 43)
7596 * presentation, of agenda items: Presentation and sorting.
7598 * printing sparse trees: Sparse trees. (line 41)
7599 * priorities: Priorities. (line 6)
7600 * priorities, of agenda items: Sorting of agenda items.
7602 * progress logging: Progress logging. (line 6)
7603 * projects, for publishing: Project alist. (line 6)
7604 * promotion, of subtrees: Structure editing. (line 6)
7605 * properties: Properties and columns.
7607 * properties, API <1>: Using the property API.
7609 * properties, API: Property API. (line 6)
7610 * properties, column view: Defining columns. (line 6)
7611 * properties, searching: Property searches. (line 6)
7612 * properties, special: Special properties. (line 6)
7613 * property syntax: Property syntax. (line 6)
7614 * publishing: Publishing. (line 6)
7615 * quoted HTML tags: Export options. (line 25)
7616 * radio tables: Radio tables. (line 6)
7617 * radio targets: Radio targets. (line 6)
7618 * range references: References. (line 60)
7619 * ranges, time: Time stamps. (line 6)
7620 * recomputing table fields: Updating the table. (line 6)
7621 * references: References. (line 6)
7622 * references, named: References. (line 82)
7623 * references, to fields: References. (line 15)
7624 * references, to ranges: References. (line 60)
7625 * region, active <1>: HTML Export commands.
7627 * region, active <2>: ASCII export. (line 9)
7628 * region, active <3>: Built-in table editor.
7630 * region, active: Structure editing. (line 64)
7631 * regular expressions, with tags search: Tag searches. (line 63)
7632 * remember.el <1>: Cooperation. (line 33)
7633 * remember.el: Remember. (line 6)
7634 * remote editing, from agenda: Agenda commands. (line 106)
7635 * remote editing, undo: Agenda commands. (line 107)
7636 * richer text: Enhancing text. (line 6)
7637 * RMAIL links: External links. (line 6)
7638 * SCHEDULED keyword: Deadlines and scheduling.
7640 * scheduling: Time stamps. (line 6)
7641 * Scripts, for agenda processing: Extracting Agenda Information for other programs.
7643 * search option in file links: Search options. (line 6)
7644 * search strings, custom: Custom searches. (line 6)
7645 * searching for tags: Tag searches. (line 6)
7646 * section-numbers: Export options. (line 25)
7647 * setting tags: Setting tags. (line 6)
7648 * SHELL links: External links. (line 6)
7649 * show all, command: Visibility cycling. (line 33)
7650 * show all, global visibility state: Visibility cycling. (line 22)
7651 * show hidden text: Visibility cycling. (line 6)
7652 * showall, STARTUP keyword: In-buffer settings. (line 61)
7653 * showstars, STARTUP keyword: In-buffer settings. (line 83)
7654 * sorting, of agenda items: Sorting of agenda items.
7656 * sparse tree, for deadlines: Inserting deadline/schedule.
7658 * sparse tree, for TODO: TODO basics. (line 34)
7659 * sparse tree, tag based: Tags. (line 6)
7660 * sparse trees: Sparse trees. (line 6)
7661 * special keywords: In-buffer settings. (line 6)
7662 * spreadsheet capabilities: The spreadsheet. (line 6)
7663 * statistics, for checkboxes: Checkboxes. (line 23)
7664 * storing links: Handling links. (line 9)
7665 * structure editing: Structure editing. (line 6)
7666 * structure of document: Document structure. (line 6)
7667 * sublevels, inclusion into tags match: Tag inheritance. (line 6)
7668 * sublevels, inclusion into todo list: Global TODO list. (line 34)
7669 * subscript: Subscripts and Superscripts.
7671 * subtree cycling: Visibility cycling. (line 10)
7672 * subtree visibility states: Visibility cycling. (line 10)
7673 * subtree, cut and paste: Structure editing. (line 6)
7674 * subtree, subtree visibility state: Visibility cycling. (line 10)
7675 * subtrees, cut and paste: Structure editing. (line 6)
7676 * summary: Summary. (line 6)
7677 * superscript: Subscripts and Superscripts.
7679 * syntax, of formulas: Formula syntax for Calc.
7681 * table editor, built-in: Built-in table editor.
7683 * table editor, table.el: Cooperation. (line 37)
7684 * table of contents: Export options. (line 25)
7685 * table.el: Cooperation. (line 34)
7686 * tables <1>: Export options. (line 25)
7687 * tables: Tables. (line 6)
7688 * tables, export: Enhancing text. (line 24)
7689 * tables, in other modes: Tables in arbitrary syntax.
7691 * tag completion: Completion. (line 6)
7692 * tag searches: Tag searches. (line 6)
7693 * tags: Tags. (line 6)
7694 * tags view: Matching tags and properties.
7696 * tags, setting: Setting tags. (line 6)
7697 * targets, for links: Internal links. (line 6)
7698 * targets, radio: Radio targets. (line 6)
7699 * tasks, breaking down: Breaking down tasks. (line 6)
7700 * templates, for remember: Remember templates. (line 6)
7701 * TeX interpretation: Embedded LaTeX. (line 6)
7702 * TeX macros <1>: Export options. (line 25)
7703 * TeX macros: Math symbols. (line 6)
7704 * TeX macros, export: Enhancing text. (line 21)
7705 * TeX symbol completion: Completion. (line 6)
7706 * TeX-like syntax for sub- and superscripts: Export options. (line 25)
7707 * thanks: History and Acknowledgments.
7709 * time format, custom: Custom time format. (line 6)
7710 * time grid: Time-of-day specifications.
7712 * time info, in export: Export options. (line 25)
7713 * time stamps <1>: Time stamps. (line 6)
7714 * time stamps: Timestamps. (line 6)
7715 * time, reading in minibuffer: The date/time prompt.
7717 * time-of-day specification: Time-of-day specifications.
7719 * time-sorted view: Timeline. (line 6)
7720 * timeline, single file: Timeline. (line 6)
7721 * timerange: Time stamps. (line 41)
7722 * timestamp: Time stamps. (line 14)
7723 * timestamp, inactive: Time stamps. (line 50)
7724 * timestamp, with repeater interval: Time stamps. (line 25)
7725 * timestamps, creating: Creating timestamps. (line 6)
7726 * TODO items: TODO items. (line 6)
7727 * TODO keyword matching: Global TODO list. (line 17)
7728 * TODO keyword matching, with tags search: Tag searches. (line 40)
7729 * todo keyword sets: Multiple sets in one file.
7731 * TODO keywords completion: Completion. (line 6)
7732 * TODO list, global: Global TODO list. (line 6)
7733 * TODO types: TODO types. (line 6)
7734 * TODO workflow: Workflow states. (line 6)
7735 * transient-mark-mode <1>: HTML Export commands.
7737 * transient-mark-mode <2>: ASCII export. (line 9)
7738 * transient-mark-mode <3>: Built-in table editor.
7740 * transient-mark-mode: Structure editing. (line 64)
7741 * translator function: Translator functions.
7743 * trees, sparse: Sparse trees. (line 6)
7744 * trees, visibility: Visibility cycling. (line 6)
7745 * tty keybindings: TTY keys. (line 6)
7746 * types as TODO keywords: TODO types. (line 6)
7747 * underlined text: Enhancing text. (line 15)
7748 * undoing remote-editing events: Agenda commands. (line 107)
7749 * updating, table: Updating the table. (line 6)
7750 * URL links: External links. (line 6)
7751 * USENET links: External links. (line 6)
7752 * variables, for customization: Customization. (line 6)
7753 * vectors, in table calculations: Formula syntax for Calc.
7755 * visibility cycling: Visibility cycling. (line 6)
7756 * visibility cycling, drawers: Drawers. (line 6)
7757 * visible text, printing: Sparse trees. (line 41)
7758 * VM links: External links. (line 6)
7759 * WANDERLUST links: External links. (line 6)
7760 * weekly agenda: Weekly/Daily agenda. (line 6)
7761 * windmove.el: Conflicts. (line 32)
7762 * workflow states as TODO keywords: Workflow states. (line 6)
7763 * XEmacs: Installation. (line 6)
7764 * XOXO export: XOXO export. (line 6)
7767 File: org, Node: Key Index, Prev: Index, Up: Top
7775 * $: Agenda commands. (line 121)
7776 * ': CDLaTeX mode. (line 43)
7777 * +: Agenda commands. (line 143)
7778 * ,: Agenda commands. (line 135)
7779 * -: Agenda commands. (line 149)
7780 * .: Agenda commands. (line 98)
7781 * :: Agenda commands. (line 129)
7782 * < <1>: The date/time prompt.
7784 * <: Using column view. (line 54)
7785 * <left>: Agenda commands. (line 95)
7786 * <RET> <1>: Agenda commands. (line 39)
7787 * <RET> <2>: The date/time prompt.
7789 * <RET> <3>: Setting tags. (line 76)
7790 * <RET>: Built-in table editor.
7792 * <right>: Agenda commands. (line 90)
7793 * <SPC> <1>: Agenda commands. (line 28)
7794 * <SPC>: Setting tags. (line 73)
7795 * <TAB> <1>: CDLaTeX mode. (line 23)
7796 * <TAB> <2>: Agenda commands. (line 33)
7797 * <TAB> <3>: Setting tags. (line 68)
7798 * <TAB> <4>: Editing and debugging formulas.
7800 * <TAB> <5>: Built-in table editor.
7802 * <TAB> <6>: Plain lists. (line 41)
7803 * <TAB>: Visibility cycling. (line 10)
7804 * > <1>: Agenda commands. (line 171)
7805 * > <2>: The date/time prompt.
7807 * >: Using column view. (line 54)
7808 * ^: CDLaTeX mode. (line 33)
7809 * _: CDLaTeX mode. (line 33)
7810 * `: CDLaTeX mode. (line 39)
7811 * a <1>: Agenda commands. (line 132)
7812 * a: Using column view. (line 43)
7813 * b: Agenda commands. (line 49)
7814 * C: Agenda commands. (line 211)
7815 * c: Agenda commands. (line 191)
7816 * C-#: Advanced features. (line 9)
7817 * C-': Agenda files. (line 18)
7818 * C-,: Agenda files. (line 18)
7819 * C-_: Agenda commands. (line 107)
7820 * C-c ! <1>: Footnotes. (line 14)
7821 * C-c !: Creating timestamps. (line 19)
7822 * C-c #: Checkboxes. (line 57)
7823 * C-c %: Handling links. (line 81)
7824 * C-c &: Handling links. (line 85)
7825 * C-c ': Editing and debugging formulas.
7827 * C-c *: Updating the table. (line 13)
7828 * C-c +: Built-in table editor.
7830 * C-c ,: Priorities. (line 18)
7831 * C-c - <1>: Built-in table editor.
7833 * C-c -: Plain lists. (line 88)
7834 * C-c .: Creating timestamps. (line 10)
7835 * C-c /: Sparse trees. (line 15)
7836 * C-c :: Enhancing text. (line 32)
7837 * C-c ;: Comment lines. (line 10)
7838 * C-c <: Creating timestamps. (line 23)
7839 * C-c <TAB>: Built-in table editor.
7841 * C-c = <1>: Editing and debugging formulas.
7843 * C-c =: Column formulas. (line 26)
7844 * C-c >: Creating timestamps. (line 27)
7845 * C-c ?: Editing and debugging formulas.
7847 * C-c [: Agenda files. (line 12)
7848 * C-c \: Tag searches. (line 9)
7849 * C-c ]: Agenda files. (line 15)
7850 * C-c ^ <1>: Built-in table editor.
7852 * C-c ^: Structure editing. (line 52)
7853 * C-c `: Built-in table editor.
7855 * C-c a !: Stuck projects. (line 14)
7856 * C-c a #: Stuck projects. (line 13)
7857 * C-c a a: Weekly/Daily agenda. (line 9)
7858 * C-c a C: Storing searches. (line 9)
7859 * C-c a e: Exporting Agenda Views.
7861 * C-c a L: Timeline. (line 10)
7862 * C-c a M: Matching tags and properties.
7864 * C-c a m: Matching tags and properties.
7866 * C-c a M: Tag searches. (line 16)
7867 * C-c a m: Tag searches. (line 12)
7868 * C-c a T: Global TODO list. (line 14)
7869 * C-c a t <1>: Global TODO list. (line 9)
7870 * C-c a t: TODO basics. (line 44)
7871 * C-c C-a: Visibility cycling. (line 33)
7872 * C-c C-b: Motion. (line 15)
7873 * C-c C-c <1>: Cooperation. (line 37)
7874 * C-c C-c <2>: The very busy C-c C-c key.
7876 * C-c C-c <3>: Processing LaTeX fragments.
7878 * C-c C-c <4>: Property syntax. (line 54)
7879 * C-c C-c <5>: Setting tags. (line 10)
7880 * C-c C-c <6>: Checkboxes. (line 37)
7881 * C-c C-c <7>: TODO basics. (line 26)
7882 * C-c C-c <8>: Editing and debugging formulas.
7884 * C-c C-c <9>: Built-in table editor.
7886 * C-c C-c: Plain lists. (line 81)
7887 * C-c C-d <1>: Agenda commands. (line 156)
7888 * C-c C-d: Inserting deadline/schedule.
7890 * C-c C-e: Exporting. (line 20)
7891 * C-c C-e a: ASCII export. (line 9)
7892 * C-c C-e b: HTML Export commands.
7894 * C-c C-e c: iCalendar export. (line 21)
7895 * C-c C-e H: HTML Export commands.
7897 * C-c C-e h: HTML Export commands.
7899 * C-c C-e I: iCalendar export. (line 16)
7900 * C-c C-e i: iCalendar export. (line 14)
7901 * C-c C-e L: LaTeX export commands.
7903 * C-c C-e l: LaTeX export commands.
7905 * C-c C-e R: HTML Export commands.
7907 * C-c C-e t: Export options. (line 13)
7908 * C-c C-e v <1>: XOXO export. (line 11)
7909 * C-c C-e v: Sparse trees. (line 41)
7910 * C-c C-e v a: ASCII export. (line 16)
7911 * C-c C-e v b: HTML Export commands.
7913 * C-c C-e v H: HTML Export commands.
7915 * C-c C-e v h: HTML Export commands.
7917 * C-c C-e v L: LaTeX export commands.
7919 * C-c C-e v l: LaTeX export commands.
7921 * C-c C-e v R: HTML Export commands.
7923 * C-c C-e x: XOXO export. (line 10)
7924 * C-c C-f: Motion. (line 12)
7925 * C-c C-j: Motion. (line 21)
7926 * C-c C-l: Handling links. (line 25)
7927 * C-c C-n: Motion. (line 8)
7928 * C-c C-o <1>: Creating timestamps. (line 31)
7929 * C-c C-o: Handling links. (line 58)
7930 * C-c C-p: Motion. (line 9)
7931 * C-c C-q <1>: Editing and debugging formulas.
7933 * C-c C-q: Built-in table editor.
7935 * C-c C-r <1>: Editing and debugging formulas.
7937 * C-c C-r: Visibility cycling. (line 34)
7938 * C-c C-s <1>: Agenda commands. (line 153)
7939 * C-c C-s: Inserting deadline/schedule.
7941 * C-c C-t <1>: Clocking work time. (line 27)
7942 * C-c C-t: TODO basics. (line 13)
7943 * C-c C-u: Motion. (line 18)
7944 * C-c C-v: TODO basics. (line 34)
7945 * C-c C-w: Inserting deadline/schedule.
7947 * C-c C-x b: Visibility cycling. (line 41)
7948 * C-c C-x C-a: ARCHIVE tag. (line 28)
7949 * C-c C-x C-b: Checkboxes. (line 39)
7950 * C-c C-x C-c <1>: Agenda commands. (line 218)
7951 * C-c C-x C-c: Using column view. (line 9)
7952 * C-c C-x C-d: Clocking work time. (line 35)
7953 * C-c C-x C-i: Clocking work time. (line 12)
7954 * C-c C-x C-k: Structure editing. (line 39)
7955 * C-c C-x C-l: Processing LaTeX fragments.
7957 * C-c C-x C-n: Handling links. (line 91)
7958 * C-c C-x C-o: Clocking work time. (line 14)
7959 * C-c C-x C-p: Handling links. (line 91)
7960 * C-c C-x C-r: Clocking work time. (line 43)
7961 * C-c C-x C-s: Moving subtrees. (line 10)
7962 * C-c C-x C-t: Custom time format. (line 12)
7963 * C-c C-x C-u: Dynamic blocks. (line 21)
7964 * C-c C-x C-w <1>: Built-in table editor.
7966 * C-c C-x C-w: Structure editing. (line 39)
7967 * C-c C-x C-x: Clocking work time. (line 31)
7968 * C-c C-x C-y <1>: Built-in table editor.
7970 * C-c C-x C-y: Structure editing. (line 46)
7971 * C-c C-x M-w <1>: Built-in table editor.
7973 * C-c C-x M-w: Structure editing. (line 43)
7974 * C-c C-y <1>: Clocking work time. (line 22)
7975 * C-c C-y: Creating timestamps. (line 48)
7976 * C-c l: Handling links. (line 9)
7977 * C-c { <1>: CDLaTeX mode. (line 21)
7978 * C-c {: Editing and debugging formulas.
7980 * C-c |: Built-in table editor.
7982 * C-c }: Editing and debugging formulas.
7984 * C-c ~: Cooperation. (line 48)
7985 * C-k: Agenda commands. (line 115)
7986 * C-S-<left>: Multiple sets in one file.
7988 * C-S-<right>: Multiple sets in one file.
7990 * C-TAB: ARCHIVE tag. (line 38)
7991 * C-u C-c *: Updating the table. (line 16)
7992 * C-u C-c .: Creating timestamps. (line 14)
7993 * C-u C-c = <1>: Editing and debugging formulas.
7995 * C-u C-c =: Field formulas. (line 24)
7996 * C-u C-c C-c: Updating the table. (line 19)
7997 * C-u C-c C-l: Handling links. (line 43)
7998 * C-u C-c C-x C-a: ARCHIVE tag. (line 31)
7999 * C-u C-c C-x C-s: Moving subtrees. (line 14)
8000 * C-u C-c C-x C-u <1>: Dynamic blocks. (line 22)
8001 * C-u C-c C-x C-u: Clocking work time. (line 70)
8002 * C-u C-u C-c *: Updating the table. (line 22)
8003 * C-u C-u C-c =: Editing and debugging formulas.
8005 * C-u C-u C-c C-c: Updating the table. (line 22)
8006 * C-x C-s: Editing and debugging formulas.
8008 * C-x C-w <1>: Exporting Agenda Views.
8010 * C-x C-w: Agenda commands. (line 227)
8011 * D: Agenda commands. (line 72)
8012 * d: Agenda commands. (line 66)
8013 * e: Using column view. (line 33)
8014 * f: Agenda commands. (line 42)
8015 * g: Agenda commands. (line 76)
8016 * H: Agenda commands. (line 215)
8017 * i: Agenda commands. (line 196)
8018 * I: Agenda commands. (line 176)
8019 * l: Agenda commands. (line 55)
8020 * L: Agenda commands. (line 30)
8021 * M: Agenda commands. (line 202)
8022 * m: Agenda commands. (line 66)
8023 * M-<down> <1>: Editing and debugging formulas.
8025 * M-<down>: Built-in table editor.
8027 * M-<left> <1>: Built-in table editor.
8029 * M-<left>: Structure editing. (line 21)
8030 * M-<RET> <1>: Plain lists. (line 49)
8031 * M-<RET>: Structure editing. (line 6)
8032 * M-<right> <1>: Built-in table editor.
8034 * M-<right>: Structure editing. (line 24)
8035 * M-<TAB> <1>: Completion. (line 10)
8036 * M-<TAB> <2>: Property syntax. (line 46)
8037 * M-<TAB> <3>: Setting tags. (line 6)
8038 * M-<TAB> <4>: Per file keywords. (line 23)
8039 * M-<TAB>: Editing and debugging formulas.
8041 * M-<up> <1>: Editing and debugging formulas.
8043 * M-<up>: Built-in table editor.
8045 * M-S-<down> <1>: Editing and debugging formulas.
8047 * M-S-<down> <2>: Built-in table editor.
8049 * M-S-<down> <3>: Plain lists. (line 66)
8050 * M-S-<down>: Structure editing. (line 36)
8051 * M-S-<left> <1>: The date/time prompt.
8053 * M-S-<left> <2>: Built-in table editor.
8055 * M-S-<left> <3>: Plain lists. (line 72)
8056 * M-S-<left>: Structure editing. (line 27)
8057 * M-S-<RET> <1>: Checkboxes. (line 54)
8058 * M-S-<RET> <2>: Plain lists. (line 59)
8059 * M-S-<RET>: Structure editing. (line 18)
8060 * M-S-<right> <1>: The date/time prompt.
8062 * M-S-<right> <2>: Built-in table editor.
8064 * M-S-<right> <3>: Plain lists. (line 72)
8065 * M-S-<right>: Structure editing. (line 30)
8066 * M-S-<up> <1>: Editing and debugging formulas.
8068 * M-S-<up> <2>: Built-in table editor.
8070 * M-S-<up> <3>: Plain lists. (line 66)
8071 * M-S-<up>: Structure editing. (line 33)
8072 * mouse-1 <1>: Agenda commands. (line 33)
8073 * mouse-1 <2>: The date/time prompt.
8075 * mouse-1: Handling links. (line 72)
8076 * mouse-2 <1>: Agenda commands. (line 33)
8077 * mouse-2: Handling links. (line 72)
8078 * mouse-3 <1>: Agenda commands. (line 28)
8079 * mouse-3: Handling links. (line 77)
8080 * n <1>: Agenda commands. (line 19)
8081 * n: Using column view. (line 30)
8082 * O: Agenda commands. (line 180)
8083 * o: Agenda commands. (line 65)
8084 * P: Agenda commands. (line 140)
8085 * p <1>: Agenda commands. (line 20)
8086 * p: Using column view. (line 30)
8087 * q <1>: Agenda commands. (line 238)
8088 * q: Using column view. (line 17)
8089 * r <1>: Agenda commands. (line 80)
8090 * r: Global TODO list. (line 22)
8091 * S: Agenda commands. (line 206)
8092 * s: Agenda commands. (line 87)
8093 * S-<down> <1>: Agenda commands. (line 149)
8094 * S-<down> <2>: The date/time prompt.
8096 * S-<down> <3>: Creating timestamps. (line 40)
8097 * S-<down> <4>: Priorities. (line 23)
8098 * S-<down> <5>: Editing and debugging formulas.
8100 * S-<down>: Plain lists. (line 62)
8101 * S-<left> <1>: Agenda commands. (line 167)
8102 * S-<left> <2>: The date/time prompt.
8104 * S-<left> <3>: Creating timestamps. (line 35)
8105 * S-<left> <4>: Using column view. (line 26)
8106 * S-<left> <5>: Property syntax. (line 62)
8107 * S-<left> <6>: Multiple sets in one file.
8109 * S-<left> <7>: TODO basics. (line 20)
8110 * S-<left>: Editing and debugging formulas.
8112 * S-<RET>: Built-in table editor.
8114 * S-<right> <1>: Agenda commands. (line 159)
8115 * S-<right> <2>: The date/time prompt.
8117 * S-<right> <3>: Creating timestamps. (line 35)
8118 * S-<right> <4>: Using column view. (line 26)
8119 * S-<right> <5>: Property syntax. (line 62)
8120 * S-<right> <6>: Multiple sets in one file.
8122 * S-<right> <7>: TODO basics. (line 20)
8123 * S-<right>: Editing and debugging formulas.
8125 * S-<TAB> <1>: Built-in table editor.
8127 * S-<TAB>: Visibility cycling. (line 22)
8128 * S-<up> <1>: Agenda commands. (line 143)
8129 * S-<up> <2>: The date/time prompt.
8131 * S-<up> <3>: Creating timestamps. (line 40)
8132 * S-<up> <4>: Priorities. (line 23)
8133 * S-<up> <5>: Editing and debugging formulas.
8135 * S-<up>: Plain lists. (line 62)
8136 * S-M-<left>: Using column view. (line 58)
8137 * S-M-<RET>: TODO basics. (line 52)
8138 * S-M-<right>: Using column view. (line 55)
8139 * T: Agenda commands. (line 124)
8140 * t: Agenda commands. (line 111)
8141 * v: Using column view. (line 39)
8142 * w: Agenda commands. (line 66)
8143 * x: Agenda commands. (line 239)
8144 * X: Agenda commands. (line 183)
8145 * y: Agenda commands. (line 66)
8151 Node: Introduction
\x7f12966
8152 Node: Summary
\x7f13381
8153 Node: Installation
\x7f16533
8154 Node: Activation
\x7f17911
8155 Node: Feedback
\x7f19148
8156 Node: Document structure
\x7f21224
8157 Node: Outlines
\x7f22116
8158 Node: Headlines
\x7f22781
8159 Ref: Headlines-Footnote-1
\x7f23785
8160 Node: Visibility cycling
\x7f23896
8161 Ref: Visibility cycling-Footnote-1
\x7f26106
8162 Ref: Visibility cycling-Footnote-2
\x7f26164
8163 Ref: Visibility cycling-Footnote-3
\x7f26214
8164 Node: Motion
\x7f26484
8165 Node: Structure editing
\x7f27438
8166 Node: Archiving
\x7f30277
8167 Node: ARCHIVE tag
\x7f30835
8168 Node: Moving subtrees
\x7f32628
8169 Node: Sparse trees
\x7f34100
8170 Ref: Sparse trees-Footnote-1
\x7f36235
8171 Ref: Sparse trees-Footnote-2
\x7f36417
8172 Node: Plain lists
\x7f36532
8173 Ref: Plain lists-Footnote-1
\x7f40729
8174 Ref: Plain lists-Footnote-2
\x7f41087
8175 Node: Drawers
\x7f41268
8176 Node: orgstruct-mode
\x7f42106
8177 Node: Tables
\x7f43006
8178 Node: Built-in table editor
\x7f43587
8179 Node: Narrow columns
\x7f50832
8180 Ref: Narrow columns-Footnote-1
\x7f52767
8181 Node: Column groups
\x7f52813
8182 Node: orgtbl-mode
\x7f54346
8183 Node: The spreadsheet
\x7f55149
8184 Node: References
\x7f56236
8185 Ref: References-Footnote-1
\x7f60700
8186 Node: Formula syntax for Calc
\x7f60989
8187 Node: Formula syntax for Lisp
\x7f63446
8188 Node: Field formulas
\x7f65164
8189 Node: Column formulas
\x7f66472
8190 Node: Editing and debugging formulas
\x7f68071
8191 Node: Updating the table
\x7f72224
8192 Node: Advanced features
\x7f73277
8193 Node: Hyperlinks
\x7f77802
8194 Node: Link format
\x7f78640
8195 Node: Internal links
\x7f79933
8196 Ref: Internal links-Footnote-1
\x7f81858
8197 Node: Radio targets
\x7f81993
8198 Node: External links
\x7f82693
8199 Node: Handling links
\x7f85097
8200 Ref: Handling links-Footnote-1
\x7f90394
8201 Ref: Handling links-Footnote-2
\x7f90631
8202 Node: Using links outside Org-mode
\x7f90705
8203 Node: Link abbreviations
\x7f91215
8204 Node: Search options
\x7f92908
8205 Ref: Search options-Footnote-1
\x7f94688
8206 Node: Custom searches
\x7f94769
8207 Node: Remember
\x7f95817
8208 Node: Setting up remember
\x7f96804
8209 Node: Remember templates
\x7f97386
8210 Ref: Remember templates-Footnote-1
\x7f100832
8211 Node: Storing notes
\x7f100930
8212 Node: TODO items
\x7f102817
8213 Node: TODO basics
\x7f103794
8214 Node: TODO extensions
\x7f105876
8215 Node: Workflow states
\x7f106695
8216 Ref: Workflow states-Footnote-1
\x7f107870
8217 Node: TODO types
\x7f107963
8218 Ref: TODO types-Footnote-1
\x7f109546
8219 Node: Multiple sets in one file
\x7f109628
8220 Node: Per file keywords
\x7f111239
8221 Ref: Per file keywords-Footnote-1
\x7f112508
8222 Node: Priorities
\x7f112709
8223 Node: Breaking down tasks
\x7f114319
8224 Ref: Breaking down tasks-Footnote-1
\x7f114839
8225 Node: Checkboxes
\x7f114935
8226 Node: Tags
\x7f117784
8227 Node: Tag inheritance
\x7f118556
8228 Node: Setting tags
\x7f119493
8229 Ref: Setting tags-Footnote-1
\x7f124016
8230 Ref: Setting tags-Footnote-2
\x7f124128
8231 Node: Tag searches
\x7f124211
8232 Node: Properties and columns
\x7f126928
8233 Node: Property syntax
\x7f128033
8234 Node: Special properties
\x7f130454
8235 Node: Property searches
\x7f131370
8236 Node: Column view
\x7f132025
8237 Node: Defining columns
\x7f133192
8238 Node: Scope of column definitions
\x7f133590
8239 Node: Column attributes
\x7f134512
8240 Node: Using column view
\x7f136760
8241 Node: Property API
\x7f138747
8242 Node: Timestamps
\x7f139101
8243 Node: Time stamps
\x7f139562
8244 Ref: Time stamps-Footnote-1
\x7f141990
8245 Node: Creating timestamps
\x7f142106
8246 Node: The date/time prompt
\x7f144180
8247 Ref: The date/time prompt-Footnote-1
\x7f146168
8248 Node: Custom time format
\x7f146274
8249 Node: Deadlines and scheduling
\x7f147966
8250 Ref: Deadlines and scheduling-Footnote-1
\x7f149586
8251 Node: Inserting deadline/schedule
\x7f149741
8252 Node: Repeated tasks
\x7f150679
8253 Node: Progress logging
\x7f152318
8254 Node: Closing items
\x7f152973
8255 Ref: Closing items-Footnote-1
\x7f153907
8256 Ref: Closing items-Footnote-2
\x7f153976
8257 Node: Tracking TODO state changes
\x7f154049
8258 Node: Clocking work time
\x7f154905
8259 Ref: Clocking work time-Footnote-1
\x7f158551
8260 Ref: Clocking work time-Footnote-2
\x7f158629
8261 Node: Agenda views
\x7f158755
8262 Node: Agenda files
\x7f160706
8263 Ref: Agenda files-Footnote-1
\x7f161672
8264 Ref: Agenda files-Footnote-2
\x7f161821
8265 Node: Agenda dispatcher
\x7f162014
8266 Node: Built-in agenda views
\x7f163711
8267 Node: Weekly/Daily agenda
\x7f164291
8268 Node: Global TODO list
\x7f167233
8269 Node: Matching tags and properties
\x7f169511
8270 Node: Timeline
\x7f170600
8271 Node: Stuck projects
\x7f171272
8272 Node: Presentation and sorting
\x7f173123
8273 Node: Categories
\x7f173914
8274 Node: Time-of-day specifications
\x7f174578
8275 Node: Sorting of agenda items
\x7f176549
8276 Node: Agenda commands
\x7f177831
8277 Node: Custom agenda views
\x7f185112
8278 Node: Storing searches
\x7f185831
8279 Node: Block agenda
\x7f187743
8280 Node: Setting Options
\x7f188973
8281 Node: Exporting Agenda Views
\x7f191712
8282 Ref: Exporting Agenda Views-Footnote-1
\x7f195996
8283 Ref: Exporting Agenda Views-Footnote-2
\x7f196053
8284 Node: Extracting Agenda Information for other programs
\x7f196239
8285 Node: Embedded LaTeX
\x7f200365
8286 Ref: Embedded LaTeX-Footnote-1
\x7f201459
8287 Node: Math symbols
\x7f201649
8288 Node: Subscripts and Superscripts
\x7f202416
8289 Node: LaTeX fragments
\x7f203262
8290 Ref: LaTeX fragments-Footnote-1
\x7f205495
8291 Ref: LaTeX fragments-Footnote-2
\x7f205756
8292 Node: Processing LaTeX fragments
\x7f205890
8293 Node: CDLaTeX mode
\x7f206838
8294 Ref: CDLaTeX mode-Footnote-1
\x7f209324
8295 Node: Exporting
\x7f209472
8296 Node: ASCII export
\x7f210939
8297 Node: HTML export
\x7f212440
8298 Node: HTML Export commands
\x7f213066
8299 Node: Quoting HTML tags
\x7f214853
8300 Node: Links
\x7f215488
8301 Node: Images
\x7f216185
8302 Ref: Images-Footnote-1
\x7f217056
8303 Node: CSS support
\x7f217117
8304 Ref: CSS support-Footnote-1
\x7f218436
8305 Node: LaTeX export
\x7f218549
8306 Node: LaTeX export commands
\x7f218873
8307 Node: Quoting LaTeX code
\x7f220035
8308 Node: XOXO export
\x7f220540
8309 Node: iCalendar export
\x7f220980
8310 Node: Text interpretation
\x7f222199
8311 Node: Comment lines
\x7f222790
8312 Node: Initial text
\x7f223185
8313 Node: Footnotes
\x7f224854
8314 Node: Enhancing text
\x7f225669
8315 Ref: Enhancing text-Footnote-1
\x7f227538
8316 Node: Export options
\x7f227628
8317 Node: Publishing
\x7f229904
8318 Ref: Publishing-Footnote-1
\x7f230865
8319 Ref: Publishing-Footnote-2
\x7f231009
8320 Node: Configuration
\x7f231160
8321 Node: Project alist
\x7f231878
8322 Node: Sources and destinations
\x7f232944
8323 Node: Selecting files
\x7f233674
8324 Node: Publishing action
\x7f234422
8325 Node: Publishing options
\x7f235756
8326 Node: Publishing links
\x7f238131
8327 Node: Project page index
\x7f239644
8328 Node: Sample configuration
\x7f240422
8329 Node: Simple example
\x7f240914
8330 Node: Complex example
\x7f241587
8331 Node: Triggering publication
\x7f243663
8332 Node: Miscellaneous
\x7f244348
8333 Node: Completion
\x7f244982
8334 Node: Customization
\x7f246652
8335 Node: In-buffer settings
\x7f247235
8336 Node: The very busy C-c C-c key
\x7f252762
8337 Node: Clean view
\x7f254523
8338 Node: TTY keys
\x7f257100
8339 Node: Interaction
\x7f258710
8340 Node: Cooperation
\x7f259107
8341 Node: Conflicts
\x7f261983
8342 Node: Bugs
\x7f263986
8343 Node: Extensions and Hacking
\x7f265482
8344 Node: Extensions
\x7f266207
8345 Node: Adding hyperlink types
\x7f268150
8346 Node: Tables in arbitrary syntax
\x7f271812
8347 Node: Radio tables
\x7f272901
8348 Node: A LaTeX example
\x7f275404
8349 Ref: A LaTeX example-Footnote-1
\x7f279050
8350 Ref: A LaTeX example-Footnote-2
\x7f279198
8351 Node: Translator functions
\x7f279633
8352 Ref: Translator functions-Footnote-1
\x7f282742
8353 Node: Dynamic blocks
\x7f282830
8354 Node: Special agenda views
\x7f284802
8355 Node: Using the property API
\x7f287980
8356 Node: History and Acknowledgments
\x7f289461
8357 Node: Index
\x7f296037
8358 Node: Key Index
\x7f330529