1 #+title: The Org Manual
3 #+texinfo: @insertcopying
7 :DESCRIPTION: Getting started.
13 :DESCRIPTION: Brief summary of what Org does.
17 Org is a mode for keeping notes, maintaining TODO lists, and project
18 planning with a fast and effective plain-text markup language. It
19 also is an authoring system with unique support for literate
20 programming and reproducible research.
22 Org is implemented on top of Outline mode, which makes it possible to
23 keep the content of large files well structured. Visibility cycling
24 and structure editing help to work with the tree. Tables are easily
25 created with a built-in table editor. Plain text URL-like links
26 connect to websites, emails, Usenet messages, BBDB entries, and any
27 files related to the projects.
29 Org develops organizational tasks around notes files that contain
30 lists or information about projects as plain text. Project planning
31 and task management make use of metadata which is part of an outline
32 node. Based on this data, specific entries can be extracted in
33 queries and create dynamic /agenda views/ that also integrate the
34 Emacs calendar and diary. Org can be used to implement many different
35 project planning schemes, such as David Allen's GTD system.
37 Org files can serve as a single source authoring system with export to
38 many different formats such as HTML, LaTeX, Open Document, and
39 Markdown. New export backends can be derived from existing ones, or
42 Org files can include source code blocks, which makes Org uniquely
43 suited for authoring technical documents with code examples. Org
44 source code blocks are fully functional; they can be evaluated in
45 place and their results can be captured in the file. This makes it
46 possible to create a single file reproducible research compendium.
48 Org keeps simple things simple. When first fired up, it should feel
49 like a straightforward, easy to use outliner. Complexity is not
50 imposed, but a large amount of functionality is available when needed.
51 Org is a toolbox. Many users actually run only a---very
52 personal---fraction of Org's capabilities, and know that there is more
53 whenever they need it.
55 All of this is achieved with strictly plain text files, the most
56 portable and future-proof file format. Org runs in Emacs. Emacs is
57 one of the most widely ported programs, so that Org mode is available
58 on every major platform.
61 There is a website for Org which provides links to the newest version
62 of Org, as well as additional information, frequently asked questions
63 (FAQ), links to tutorials, etc. This page is located at
64 [[https://orgmode.org]].
66 #+cindex: print edition
67 An earlier version (7.3) of this manual is available as a [[http://www.network-theory.co.uk/org/manual/][paperback
68 book from Network Theory Ltd.]].
72 :DESCRIPTION: Installing Org.
74 #+cindex: installation
76 Org is included in all recent distributions of GNU Emacs, so you
77 probably do not need to install it. Most users will simply activate
78 Org and begin exploring its many features.
80 If, for one reason or another, you want to install Org on top of this
81 pre-packaged version, there are three ways to do it:
83 - by using the Emacs package system;
84 - by downloading Org as an archive; or
85 - by using Org's git repository.
87 We *strongly recommend* sticking to a single installation method.
89 *** Using Emacs packaging system
94 Recent Emacs distributions include a packaging system which lets you
95 install Elisp libraries. You can install Org with {{{kbd(M-x
96 package-install RET org)}}}.
98 #+attr_texinfo: :tag Important
100 You need to do this in a session where no =.org= file has been
101 visited, i.e., where no Org built-in function have been loaded.
102 Otherwise autoload Org functions will mess up the installation.
105 If you want to use Org's package repository, check out the [[https://orgmode.org/elpa.html][Org ELPA
108 *** Downloading Org as an archive
113 You can download Org latest release from [[https://orgmode.org/][Org's website]]. In this case,
114 make sure you set the load-path correctly in your Emacs init file:
116 #+begin_src emacs-lisp
117 (add-to-list 'load-path "~/path/to/orgdir/lisp")
120 The downloaded archive contains contributed libraries that are not
121 included in Emacs. If you want to use them, add the =contrib/=
122 directory to your load-path:
124 #+begin_src emacs-lisp
125 (add-to-list 'load-path "~/path/to/orgdir/contrib/lisp" t)
128 Optionally, you can compile the files and/or install them in your
129 system. Run =make help= to list compilation and installation options.
131 *** Using Org's git repository
136 You can clone Org's repository and install Org like this:
140 $ git clone git@code.orgmode.org:bzg/org-mode.git
145 Note that in this case, ~make autoloads~ is mandatory: it defines
146 Org's version in =org-version.el= and Org's autoloads in
149 Remember to add the correct load-path as described in the method
152 You can also compile with =make=, generate the documentation with
153 =make doc=, create a local configuration with =make config= and
154 install Org with =make install=. Please run =make help= to get the
155 list of compilation/installation options.
157 For more detailed explanations on Org's build system, please check the
158 Org Build System page on [[https://orgmode.org/worg/dev/org-build-system.html][Worg]].
162 :DESCRIPTION: How to activate Org for certain buffers.
167 #+cindex: global key bindings
168 #+cindex: key bindings, global
170 Org mode buffers need Font Lock to be turned on: this is the default
173 There are compatibility issues between Org mode and some other Elisp
174 packages (see [[*Packages that conflict with Org mode]]). Please take the
175 time to check the list.
178 #+findex: org-capture
179 #+findex: org-store-link
180 For a better experience, the three Org commands ~org-store-link~,
181 ~org-capture~ and ~org-agenda~ ought to be accessible anywhere in
182 Emacs, not just in Org buffers. To that effect, you need to bind them
183 to globally available keys, like the ones reserved for users (see
184 [[info:elisp::Key%20Binding%20Conventions]]). Here are suggested
185 bindings, please modify the keys to your own liking.
187 #+begin_src emacs-lisp
188 (global-set-key (kbd "C-c l") 'org-store-link)
189 (global-set-key (kbd "C-c a") 'org-agenda)
190 (global-set-key (kbd "C-c c") 'org-capture)
193 #+cindex: Org mode, turning on
194 Files with the =.org= extension use Org mode by default. To turn on
195 Org mode in a file that does not have the extension =.org=, make the
196 first line of a file look like this:
198 : MY PROJECTS -*- mode: org; -*-
200 #+vindex: org-insert-mode-line-in-empty-file
202 which selects Org mode for this buffer no matter what the file's name
203 is. See also the variable ~org-insert-mode-line-in-empty-file~.
205 Many commands in Org work on the region if the region is /active/. To
206 make use of this, you need to have ~transient-mark-mode~ turned on,
207 which is the default. If you do not like ~transient-mark-mode~, you
208 can create an active region by using the mouse to select a region, or
209 pressing {{{kbd(C-SPC)}}} twice before moving point.
213 :DESCRIPTION: Bug reports, ideas, patches, etc.
216 #+cindex: bug reports
217 #+cindex: reporting a bug
221 If you find problems with Org, or if you have questions, remarks, or
222 ideas about it, please send an email to the Org mailing list
223 [[mailto:emacs-orgmode@gnu.org]]. You can subscribe to the list [[https://lists.gnu.org/mailman/listinfo/emacs-orgmode][from this
224 web page]]. If you are not a member of the mailing list, your mail will
225 be passed to the list after a moderator has approved it[fn:2].
227 #+findex: org-version
228 #+findex: org-submit-bug-report
229 For bug reports, please first try to reproduce the bug with the latest
230 version of Org available---if you are running an outdated version, it
231 is quite possible that the bug has been fixed already. If the bug
232 persists, prepare a report and provide as much information as
233 possible, including the version information of Emacs ({{{kbd(M-x
234 emacs-version)}}}) and Org ({{{kbd(M-x org-version)}}}), as well as
235 the Org related setup in the Emacs init file. The easiest way to do
236 this is to use the command
238 : M-x org-submit-bug-report <RET>
241 which puts all this information into an Emacs mail buffer so that you
242 only need to add your description. If you are not sending the Email
243 from within Emacs, please copy and paste the content into your Email
246 Sometimes you might face a problem due to an error in your Emacs or
247 Org mode setup. Before reporting a bug, it is very helpful to start
248 Emacs with minimal customizations and reproduce the problem. Doing so
249 often helps you determine if the problem is with your customization or
250 with Org mode itself. You can start a typical minimal session with
251 a command like the example below.
253 : $ emacs -Q -l /path/to/minimal-org.el
255 However if you are using Org mode as distributed with Emacs, a minimal
256 setup is not necessary. In that case it is sufficient to start Emacs
257 as =emacs -Q=. The =minimal-org.el= setup file can have contents as
260 #+begin_src emacs-lisp
261 ;;; Minimal setup to load latest `org-mode'.
263 ;; Activate debugging.
264 (setq debug-on-error t
268 ;; Add latest Org mode to load path.
269 (add-to-list 'load-path (expand-file-name "/path/to/org-mode/lisp"))
270 (add-to-list 'load-path (expand-file-name "/path/to/org-mode/contrib/lisp" t))
273 If an error occurs, a "backtrace" can be very useful---see below on
274 how to create one. Often a small example file helps, along with clear
277 1. What exactly did you do?
278 2. What did you expect to happen?
279 3. What happened instead?
281 Thank you for helping to improve this program.
283 *** How to create a useful backtrace
288 #+cindex: backtrace of an error
289 If working with Org produces an error with a message you do not
290 understand, you may have hit a bug. The best way to report this is by
291 providing, in addition to what was mentioned above, a backtrace. This
292 is information from the built-in debugger about where and how the
293 error occurred. Here is how to produce a useful backtrace:
295 1. Reload uncompiled versions of all Org mode Lisp files. The
296 backtrace contains much more information if it is produced with
297 uncompiled code. To do this, use
299 : C-u M-x org-reload <RET>
302 or, from the menu: Org \rarr Refresh/Reload \rarr Reload Org uncompiled.
304 2. Then, activate the debugger:
306 : M-x toggle-debug-or-error <RET>
309 or, from the menu: Options \rarr Enter Debugger on Error.
311 3. Do whatever you have to do to hit the error. Do not forget to
312 document the steps you take.
314 4. When you hit the error, a =*Backtrace*= buffer appears on the
315 screen. Save this buffer to a file---for example using {{{kbd(C-x
316 C-w)}}}---and attach it to your bug report.
318 ** Typesetting Conventions Used in this Manual
320 :DESCRIPTION: Typesetting conventions used in this manual.
321 :ALT_TITLE: Conventions
324 *** TODO keywords, tags, properties, etc.
329 Org uses various syntactical elements: TODO keywords, tags, property
330 names, keywords, blocks, etc. In this manual we use the following
333 #+attr_texinfo: :sep ,
334 - =TODO=, =WAITING= ::
336 TODO keywords are written with all capitals, even if they are
339 - =boss=, =ARCHIVE= ::
341 Tags are case-sensitive. User-defined tags are written in
342 lowercase; built-in tags with special meaning are written as they
343 should appear in the document, usually with all capitals.
345 - =Release=, =PRIORITY= ::
347 User-defined properties are capitalized; built-in properties with
348 special meaning are written with all capitals.
350 - =TITLE=, =BEGIN= ... =END= ::
352 Keywords and blocks are written in uppercase to enhance their
353 readability, but you can use lowercase in your Org files.
355 *** Key bindings and commands
360 The manual lists both the keys and the corresponding commands for
361 accessing a functionality. Org mode often uses the same key for
362 different functions, depending on context. The command that is bound
363 to such keys has a generic name, like ~org-metaright~. In the manual
364 we will, wherever possible, give the function that is internally
365 called by the generic command. For example, in the chapter on
366 document structure, {{{kbd(M-RIGHT)}}} will be listed to call
367 ~org-do-demote~, while in the chapter on tables, it will be listed to
368 call ~org-table-move-column-right~.
372 :DESCRIPTION: A tree works like your brain.
375 #+cindex: document structure
376 #+cindex: structure of document
377 Org is an outliner. Outlines allow a document to be organized in
378 a hierarchical structure, which, least for me, is the best
379 representation of notes and thoughts. An overview of this structure
380 is achieved by folding, i.e., hiding large parts of the document to
381 show only the general document structure and the parts currently being
382 worked on. Org greatly simplifies the use of outlines by compressing
383 the entire show and hide functionalities into a single command,
384 ~org-cycle~, which is bound to the {{{kbd(TAB)}}} key.
388 :DESCRIPTION: How to typeset Org tree headlines.
391 #+cindex: outline tree
392 #+vindex: org-special-ctrl-a/e
393 #+vindex: org-special-ctrl-k
394 #+vindex: org-ctrl-k-protect-subtree
396 Headlines define the structure of an outline tree. The headlines in
397 Org start with one or more stars, on the left margin[fn:3]. For
401 ,* Top level headline
407 ,* Another top level headline
410 #+vindex: org-footnote-section
411 The name defined in ~org-footnote-section~ is reserved. Do not use it
412 as a title for your own headings.
414 Some people find the many stars too noisy and would prefer an outline
415 that has whitespace followed by a single star as headline starters.
416 See [[*A Cleaner Outline View]].
418 Headline are not numbered. However, you may want to dynamically
419 number some, or all, of them. See [[*Dynamic Headline Numbering]].
421 #+vindex: org-cycle-separator-lines
422 An empty line after the end of a subtree is considered part of it and
423 is hidden when the subtree is folded. However, if you leave at least
424 two empty lines, one empty line remains visible after folding the
425 subtree, in order to structure the collapsed view. See the variable
426 ~org-cycle-separator-lines~ to modify this behavior.
428 ** Visibility Cycling
430 :DESCRIPTION: Show and hide, much simplified.
432 #+cindex: cycling, visibility
433 #+cindex: visibility cycling
434 #+cindex: trees, visibility
435 #+cindex: show hidden text
438 *** Global and local cycling
440 :DESCRIPTION: Cycling through various visibility states.
442 #+cindex: subtree visibility states
443 #+cindex: subtree cycling
444 #+cindex: folded, subtree visibility state
445 #+cindex: children, subtree visibility state
446 #+cindex: subtree, subtree visibility state
448 Outlines make it possible to hide parts of the text in the buffer.
449 Org uses just two commands, bound to {{{kbd(TAB)}}} and
450 {{{kbd(S-TAB)}}} to change the visibility in the buffer.
452 #+attr_texinfo: :sep ,
453 - {{{kbd(TAB)}}} (~org-cycle~) ::
457 /Subtree cycling/: Rotate current subtree among the states
460 ,-> FOLDED -> CHILDREN -> SUBTREE --.
461 '-----------------------------------'
464 #+vindex: org-cycle-emulate-tab
465 Point must be on a headline for this to work[fn:4].
467 - {{{kbd(S-TAB)}}} (~org-global-cycle~), {{{kbd(C-u TAB)}}} ::
469 #+cindex: global visibility states
470 #+cindex: global cycling
471 #+cindex: overview, global visibility state
472 #+cindex: contents, global visibility state
473 #+cindex: show all, global visibility state
476 #+findex: org-global-cycle
477 /Global cycling/: Rotate the entire buffer among the states
480 ,-> OVERVIEW -> CONTENTS -> SHOW ALL --.
481 '--------------------------------------'
484 When {{{kbd(S-TAB)}}} is called with a numeric prefix argument N,
485 the CONTENTS view up to headlines of level N are shown. Note that
486 inside tables (see [[*Tables]]), {{{kbd(S-TAB)}}} jumps to the previous
489 #+vindex: org-cycle-global-at-bob
490 You can run global cycling using {{{kbd(TAB)}}} only if point is at
491 the very beginning of the buffer, but not on a headline, and
492 ~org-cycle-global-at-bob~ is set to a non-~nil~ value.
494 - {{{kbd(C-u C-u TAB)}}} (~org-set-startup-visibility~) ::
496 #+cindex: startup visibility
497 #+kindex: C-u C-u TAB
498 #+findex: org-set-startup-visibility
499 Switch back to the startup visibility of the buffer (see [[*Initial
502 - {{{kbd(C-u C-u C-u TAB)}}} (~outline-show-all~) ::
504 #+cindex: show all, command
505 #+kindex: C-u C-u C-u TAB
506 #+findex: outline-show-all
507 Show all, including drawers.
509 - {{{kbd(C-c C-r)}}} (~org-reveal~) ::
511 #+cindex: revealing context
514 Reveal context around point, showing the current entry, the
515 following heading and the hierarchy above. Useful for working near
516 a location that has been exposed by a sparse tree command (see
517 [[*Sparse Trees]]) or an agenda command (see [[*Commands in the Agenda
518 Buffer]]). With a prefix argument show, on each level, all sibling
519 headings. With a double prefix argument, also show the entire
520 subtree of the parent.
522 - {{{kbd(C-c C-k)}}} (~outline-show-branches~) ::
524 #+cindex: show branches, command
526 #+findex: outline-show-branches
527 Expose all the headings of the subtree, CONTENTS view for just one
530 - {{{kbd(C-c TAB)}}} (~outline-show-children~) ::
532 #+cindex: show children, command
534 #+findex: outline-show-children
535 Expose all direct children of the subtree. With a numeric prefix
536 argument N, expose all children down to level N.
538 - {{{kbd(C-c C-x b)}}} (~org-tree-to-indirect-buffer~) ::
541 #+findex: org-tree-to-indirect-buffer
542 Show the current subtree in an indirect buffer[fn:5]. With
543 a numeric prefix argument, N, go up to level N and then take that
544 tree. If N is negative then go up that many levels. With
545 a {{{kbd(C-u)}}} prefix, do not remove the previously used indirect
548 - {{{kbd(C-c C-x v)}}} (~org-copy-visible~) ::
551 #+findex: org-copy-visible
552 Copy the /visible/ text in the region into the kill ring.
554 *** Initial visibility
556 :DESCRIPTION: Setting the initial visibility state.
559 #+vindex: org-startup-folded
560 When Emacs first visits an Org file, the global state is set to
561 OVERVIEW, i.e., only the top level headlines are visible[fn:6]. This
562 can be configured through the variable ~org-startup-folded~, or on
563 a per-file basis by adding one of the following lines anywhere in the
566 #+cindex: @samp{STARTUP}, keyword
571 ,#+STARTUP: showeverything
574 #+cindex: @samp{VISIBILITY}, property
575 Furthermore, any entries with a =VISIBILITY= property (see [[*Properties
576 and Columns]]) get their visibility adapted accordingly. Allowed values
577 for this property are =folded=, =children=, =content=, and =all=.
579 - {{{kbd(C-u C-u TAB)}}} (~org-set-startup-visibility~) ::
581 #+kindex: C-u C-u TAB
582 #+findex: org-set-startup-visibility
583 Switch back to the startup visibility of the buffer, i.e., whatever
584 is requested by startup options and =VISIBILITY= properties in
587 *** Catching invisible edits
589 :DESCRIPTION: Preventing mistakes when editing invisible parts.
591 #+cindex: edits, catching invisible
593 #+vindex: org-catch-invisible-edits
594 Sometimes you may inadvertently edit an invisible part of the buffer
595 and be confused on what has been edited and how to undo the mistake.
596 Setting ~org-catch-invisible-edits~ to non-~nil~ helps preventing
597 this. See the docstring of this option on how Org should catch
598 invisible edits and process them.
602 :DESCRIPTION: Jumping to other headlines.
604 #+cindex: motion, between headlines
605 #+cindex: jumping, to headlines
606 #+cindex: headline navigation
608 The following commands jump to other headlines in the buffer.
610 - {{{kbd(C-c C-n)}}} (~outline-next-visible-heading~) ::
613 #+findex: outline-next-visible-heading
616 - {{{kbd(C-c C-p)}}} (~outline-previous-visible-heading~) ::
619 #+findex: outline-previous-visible-heading
622 - {{{kbd(C-c C-f)}}} (~org-forward-same-level~) ::
625 #+findex: org-forward-same-level
626 Next heading same level.
628 - {{{kbd(C-c C-b)}}} (~org-backward-same-level~) ::
631 #+findex: org-backward-same-level
632 Previous heading same level.
634 - {{{kbd(C-c C-u)}}} (~outline-up-heading~) ::
637 #+findex: outline-up-heading
638 Backward to higher level heading.
640 - {{{kbd(C-c C-j)}}} (~org-goto~) ::
644 #+vindex: org-goto-auto-isearch
645 Jump to a different place without changing the current outline
646 visibility. Shows the document structure in a temporary buffer,
647 where you can use the following keys to find your destination:
649 #+attr_texinfo: :columns 0.3 0.7
650 | {{{kbd(TAB)}}} | Cycle visibility. |
651 | {{{kbd(DOWN)}}} / {{{kbd(UP)}}} | Next/previous visible headline. |
652 | {{{kbd(RET)}}} | Select this location. |
653 | {{{kbd(/)}}} | Do a Sparse-tree search |
656 The following keys work if you turn off ~org-goto-auto-isearch~
658 #+attr_texinfo: :columns 0.3 0.7
659 | {{{kbd(n)}}} / {{{kbd(p)}}} | Next/previous visible headline. |
660 | {{{kbd(f)}}} / {{{kbd(b)}}} | Next/previous headline same level. |
661 | {{{kbd(u)}}} | One level up. |
662 | {{{kbd(0)}}} ... {{{kbd(9)}}} | Digit argument. |
663 | {{{kbd(q)}}} | Quit. |
665 #+vindex: org-goto-interface
667 See also the variable ~org-goto-interface~.
671 :DESCRIPTION: Changing sequence and level of headlines.
673 #+cindex: structure editing
674 #+cindex: headline, promotion and demotion
675 #+cindex: promotion, of subtrees
676 #+cindex: demotion, of subtrees
677 #+cindex: subtree, cut and paste
678 #+cindex: pasting, of subtrees
679 #+cindex: cutting, of subtrees
680 #+cindex: copying, of subtrees
681 #+cindex: sorting, of subtrees
682 #+cindex: subtrees, cut and paste
684 - {{{kbd(M-RET)}}} (~org-meta-return~) ::
687 #+findex: org-meta-return
688 #+vindex: org-M-RET-may-split-line
689 Insert a new heading, item or row.
691 If the command is used at the /beginning/ of a line, and if there is
692 a heading or a plain list item (see [[*Plain Lists]]) at point, the new
693 heading/item is created /before/ the current line. When used at the
694 beginning of a regular line of text, turn that line into a heading.
696 When this command is used in the middle of a line, the line is split
697 and the rest of the line becomes the new item or headline. If you
698 do not want the line to be split, customize
699 ~org-M-RET-may-split-line~.
701 Calling the command with a {{{kbd(C-u)}}} prefix unconditionally
702 inserts a new heading at the end of the current subtree, thus
703 preserving its contents. With a double {{{kbd(C-u C-u)}}} prefix,
704 the new heading is created at the end of the parent subtree instead.
706 - {{{kbd(C-RET)}}} (~org-insert-heading-respect-content~) ::
709 #+findex: org-insert-heading-respect-content
710 Insert a new heading at the end of the current subtree.
712 - {{{kbd(M-S-RET)}}} (~org-insert-todo-heading~) ::
715 #+findex: org-insert-todo-heading
716 #+vindex: org-treat-insert-todo-heading-as-state-change
717 Insert new TODO entry with same level as current heading. See also
718 the variable ~org-treat-insert-todo-heading-as-state-change~.
720 - {{{kbd(C-S-RET)}}} (~org-insert-todo-heading-respect-content~) ::
723 #+findex: org-insert-todo-heading-respect-content
724 Insert new TODO entry with same level as current heading. Like
725 {{{kbd(C-RET)}}}, the new headline is inserted after the current
728 - {{{kbd(TAB)}}} (~org-cycle~) ::
732 In a new entry with no text yet, the first {{{kbd(TAB)}}} demotes
733 the entry to become a child of the previous one. The next
734 {{{kbd(TAB)}}} makes it a parent, and so on, all the way to top
735 level. Yet another {{{kbd(TAB)}}}, and you are back to the initial
738 - {{{kbd(M-LEFT)}}} (~org-do-promote~) ::
741 #+findex: org-do-promote
742 Promote current heading by one level.
744 - {{{kbd(M-RIGHT)}}} (~org-do-demote~) ::
747 #+findex: org-do-demote
748 Demote current heading by one level.
750 - {{{kbd(M-S-LEFT)}}} (~org-promote-subtree~) ::
753 #+findex: org-promote-subtree
754 Promote the current subtree by one level.
756 - {{{kbd(M-S-RIGHT)}}} (~org-demote-subtree~) ::
759 #+findex: org-demote-subtree
760 Demote the current subtree by one level.
762 - {{{kbd(M-UP)}}} (~org-move-subtree-up~) ::
765 #+findex: org-move-subtree-up
766 Move subtree up, i.e., swap with previous subtree of same level.
768 - {{{kbd(M-DOWN)}}} (~org-move-subtree-down~) ::
771 #+findex: org-move-subtree-down
772 Move subtree down, i.e., swap with next subtree of same level.
774 - {{{kbd(C-c @)}}} (~org-mark-subtree~) ::
777 #+findex: org-mark-subtree
778 Mark the subtree at point. Hitting repeatedly marks subsequent
779 subtrees of the same level as the marked subtree.
781 - {{{kbd(C-c C-x C-w)}}} (~org-cut-subtree~) ::
783 #+kindex: C-c C-x C-w
784 #+findex: org-cut-subtree
785 Kill subtree, i.e., remove it from buffer but save in kill ring.
786 With a numeric prefix argument N, kill N sequential subtrees.
788 - {{{kbd(C-c C-x M-w)}}} (~org-copy-subtree~) ::
790 #+kindex: C-c C-x M-w
791 #+findex: org-copy-subtree
792 Copy subtree to kill ring. With a numeric prefix argument N, copy
793 the N sequential subtrees.
795 - {{{kbd(C-c C-x C-y)}}} (~org-paste-subtree~) ::
797 #+kindex: C-c C-x C-y
798 #+findex: org-paste-subtree
799 Yank subtree from kill ring. This does modify the level of the
800 subtree to make sure the tree fits in nicely at the yank position.
801 The yank level can also be specified with a numeric prefix argument,
802 or by yanking after a headline marker like =****=.
804 - {{{kbd(C-y)}}} (~org-yank~) ::
808 #+vindex: org-yank-adjusted-subtrees
809 #+vindex: org-yank-folded-subtrees
810 Depending on the variables ~org-yank-adjusted-subtrees~ and
811 ~org-yank-folded-subtrees~, Org's internal ~yank~ command pastes
812 subtrees folded and in a clever way, using the same command as
813 {{{kbd(C-c C-x C-y)}}}. With the default settings, no level
814 adjustment takes place, but the yanked tree is folded unless doing
815 so would swallow text previously visible. Any prefix argument to
816 this command forces a normal ~yank~ to be executed, with the prefix
817 passed along. A good way to force a normal yank is {{{kbd(C-u
818 C-y)}}}. If you use ~yank-pop~ after a yank, it yanks previous kill
819 items plainly, without adjustment and folding.
821 - {{{kbd(C-c C-x c)}}} (~org-clone-subtree-with-time-shift~) ::
824 #+findex: org-clone-subtree-with-time-shift
825 Clone a subtree by making a number of sibling copies of it. You are
826 prompted for the number of copies to make, and you can also specify
827 if any timestamps in the entry should be shifted. This can be
828 useful, for example, to create a number of tasks related to a series
829 of lectures to prepare. For more details, see the docstring of the
830 command ~org-clone-subtree-with-time-shift~.
832 - {{{kbd(C-c C-w)}}} (~org-refile~) ::
836 Refile entry or region to a different location. See [[*Refile and
839 - {{{kbd(C-c ^)}}} (~org-sort~) ::
843 Sort same-level entries. When there is an active region, all
844 entries in the region are sorted. Otherwise the children of the
845 current headline are sorted. The command prompts for the sorting
846 method, which can be alphabetically, numerically, by time---first
847 timestamp with active preferred, creation time, scheduled time,
848 deadline time---by priority, by TODO keyword---in the sequence the
849 keywords have been defined in the setup---or by the value of
850 a property. Reverse sorting is possible as well. You can also
851 supply your own function to extract the sorting key. With
852 a {{{kbd(C-u)}}} prefix, sorting is case-sensitive.
854 - {{{kbd(C-x n s)}}} (~org-narrow-to-subtree~) ::
857 #+findex: org-narrow-to-subtree
858 Narrow buffer to current subtree.
860 - {{{kbd(C-x n b)}}} (~org-narrow-to-block~) ::
863 #+findex: org-narrow-to-block
864 Narrow buffer to current block.
866 - {{{kbd(C-x n w)}}} (~widen~) ::
870 Widen buffer to remove narrowing.
872 - {{{kbd(C-c *)}}} (~org-toggle-heading~) ::
875 #+findex: org-toggle-heading
876 Turn a normal line or plain list item into a headline---so that it
877 becomes a subheading at its location. Also turn a headline into
878 a normal line by removing the stars. If there is an active region,
879 turn all lines in the region into headlines. If the first line in
880 the region was an item, turn only the item lines into headlines.
881 Finally, if the first line is a headline, remove the stars from all
882 headlines in the region.
884 #+cindex: region, active
885 #+cindex: active region
886 #+cindex: transient mark mode
887 When there is an active region---i.e., when Transient Mark mode is
888 active---promotion and demotion work on all headlines in the region.
889 To select a region of headlines, it is best to place both point and
890 mark at the beginning of a line, mark at the beginning of the first
891 headline, and point at the line just after the last headline to
892 change. Note that when point is inside a table (see [[*Tables]]), the
893 Meta-Cursor keys have different functionality.
897 :DESCRIPTION: Matches embedded in context.
899 #+cindex: sparse trees
900 #+cindex: trees, sparse
901 #+cindex: folding, sparse trees
902 #+cindex: occur, command
904 #+vindex: org-show-context-detail
905 An important feature of Org mode is the ability to construct /sparse
906 trees/ for selected information in an outline tree, so that the entire
907 document is folded as much as possible, but the selected information
908 is made visible along with the headline structure above it[fn:7].
909 Just try it out and you will see immediately how it works.
911 Org mode contains several commands creating such trees, all these
912 commands can be accessed through a dispatcher:
914 - {{{kbd(C-c /)}}} (~org-sparse-tree~) ::
917 #+findex: org-sparse-tree
918 This prompts for an extra key to select a sparse-tree creating
921 - {{{kbd(C-c / r)}}} or {{{kbd(C-c / /)}}} (~org-occur~) ::
926 #+vindex: org-remove-highlights-with-change
927 Prompts for a regexp and shows a sparse tree with all matches. If
928 the match is in a headline, the headline is made visible. If the
929 match is in the body of an entry, headline and body are made
930 visible. In order to provide minimal context, also the full
931 hierarchy of headlines above the match is shown, as well as the
932 headline following the match. Each match is also highlighted; the
933 highlights disappear when the buffer is changed by an editing
934 command, or by pressing {{{kbd(C-c C-c)}}}[fn:8]. When called with
935 a {{{kbd(C-u)}}} prefix argument, previous highlights are kept, so
936 several calls to this command can be stacked.
938 - {{{kbd(M-g n)}}} or {{{kbd(M-g M-n)}}} (~next-error~) ::
943 Jump to the next sparse tree match in this buffer.
945 - {{{kbd(M-g p)}}} or {{{kbd(M-g M-p)}}} (~previous-error~) ::
949 #+findex: previous-error
950 Jump to the previous sparse tree match in this buffer.
952 #+vindex: org-agenda-custom-commands
953 For frequently used sparse trees of specific search strings, you can
954 use the variable ~org-agenda-custom-commands~ to define fast keyboard
955 access to specific sparse trees. These commands will then be
956 accessible through the agenda dispatcher (see [[*The Agenda Dispatcher]]).
959 #+begin_src emacs-lisp
960 (setq org-agenda-custom-commands
961 '(("f" occur-tree "FIXME")))
965 defines the key {{{kbd(f)}}} as a shortcut for creating a sparse tree
966 matching the string =FIXME=.
968 The other sparse tree commands select headings based on TODO keywords,
969 tags, or properties and are discussed later in this manual.
972 #+cindex: printing sparse trees
973 #+cindex: visible text, printing
974 To print a sparse tree, you can use the Emacs command
975 ~ps-print-buffer-with-faces~ which does not print invisible parts of
976 the document. Or you can use the command {{{kbd(C-c C-e v)}}} to
977 export only the visible part of the document and print the resulting
982 :DESCRIPTION: Additional structure within an entry.
984 #+cindex: plain lists
985 #+cindex: lists, plain
986 #+cindex: lists, ordered
987 #+cindex: ordered lists
989 Within an entry of the outline tree, hand-formatted lists can provide
990 additional structure. They also provide a way to create lists of
991 checkboxes (see [[*Checkboxes]]). Org supports editing such lists, and
992 every exporter (see [[*Exporting]]) can parse and format them.
994 Org knows ordered lists, unordered lists, and description lists.
996 #+attr_texinfo: :indic @bullet
997 - /Unordered/ list items start with =-=, =+=, or =*=[fn:9] as bullets.
1000 #+vindex: org-plain-list-ordered-item-terminator
1001 #+vindex: org-alphabetical-lists
1002 /Ordered/ list items start with a numeral followed by either
1003 a period or a right parenthesis[fn:10], such as =1.= or =1)=[fn:11]
1004 If you want a list to start with a different value---e.g.,
1005 20---start the text of the item with =[@20]=[fn:12]. Those
1006 constructs can be used in any item of the list in order to enforce
1007 a particular numbering.
1009 - /Description/ list items are unordered list items, and contain the
1010 separator =::= to distinguish the description /term/ from the
1013 Items belonging to the same list must have the same indentation on the
1014 first line. In particular, if an ordered list reaches number =10.=,
1015 then the 2-digit numbers must be written left-aligned with the other
1016 numbers in the list. An item ends before the next line that is less
1017 or equally indented than its bullet/number.
1019 A list ends whenever every item has ended, which means before any line
1020 less or equally indented than items at top level. It also ends before
1021 two blank lines. In that case, all items are closed. Here is an
1025 ,* Lord of the Rings
1026 My favorite scenes are (in this order)
1027 1. The attack of the Rohirrim
1028 2. Eowyn's fight with the witch king
1029 + this was already my favorite scene in the book
1030 + I really like Miranda Otto.
1031 3. Peter Jackson being shot by Legolas
1033 He makes a really funny face when it happens.
1034 But in the end, no individual scenes matter but the film as a whole.
1035 Important actors in this film are:
1036 - Elijah Wood :: He plays Frodo
1037 - Sean Astin :: He plays Sam, Frodo's friend. I still remember him
1038 very well from his role as Mikey Walsh in /The Goonies/.
1041 Org supports these lists by tuning filling and wrapping commands to
1042 deal with them correctly, and by exporting them properly (see
1043 [[*Exporting]]). Since indentation is what governs the structure of these
1044 lists, many structural constructs like =#+BEGIN_= blocks can be
1045 indented to signal that they belong to a particular item.
1047 #+vindex: org-list-demote-modify-bullet
1048 #+vindex: org-list-indent-offset
1049 If you find that using a different bullet for a sub-list---than that
1050 used for the current list-level---improves readability, customize the
1051 variable ~org-list-demote-modify-bullet~. To get a greater difference
1052 of indentation between items and theirs sub-items, customize
1053 ~org-list-indent-offset~.
1055 #+vindex: org-list-automatic-rules
1056 The following commands act on items when point is in the first line of
1057 an item---the line with the bullet or number. Some of them imply the
1058 application of automatic rules to keep list structure intact. If some
1059 of these actions get in your way, configure ~org-list-automatic-rules~
1060 to disable them individually.
1062 #+attr_texinfo: :sep ,
1063 - {{{kbd(TAB)}}} (~org-cycle~) ::
1065 #+cindex: cycling, in plain lists
1068 #+vindex: org-cycle-include-plain-lists
1069 Items can be folded just like headline levels. Normally this works
1070 only if point is on a plain list item. For more details, see the
1071 variable ~org-cycle-include-plain-lists~. If this variable is set
1072 to ~integrate~, plain list items are treated like low-level
1073 headlines. The level of an item is then given by the indentation of
1074 the bullet/number. Items are always subordinate to real headlines,
1075 however; the hierarchies remain completely separated. In a new item
1076 with no text yet, the first {{{kbd(TAB)}}} demotes the item to
1077 become a child of the previous one. Subsequent {{{kbd(TAB)}}}s move
1078 the item to meaningful levels in the list and eventually get it back
1079 to its initial position.
1081 - {{{kbd(M-RET)}}} (~org-insert-heading~) ::
1084 #+findex: org-insert-heading
1085 #+vindex: org-M-RET-may-split-line
1086 Insert new item at current level. With a prefix argument, force
1087 a new heading (see [[*Structure Editing]]). If this command is used in
1088 the middle of an item, that item is /split/ in two, and the second
1089 part becomes the new item[fn:13]. If this command is executed
1090 /before item's body/, the new item is created /before/ the current
1093 - {{{kbd(M-S-RET)}}} ::
1096 Insert a new item with a checkbox (see [[*Checkboxes]]).
1098 - {{{kbd(S-UP)}}}, {{{kbd(S-DOWN)}}} ::
1102 #+cindex: shift-selection-mode
1103 #+vindex: org-support-shift-select
1104 #+vindex: org-list-use-circular-motion
1105 Jump to the previous/next item in the current list, but only if
1106 ~org-support-shift-select~ is off[fn:14]. If not, you can still use
1107 paragraph jumping commands like {{{kbd(C-UP)}}} and
1108 {{{kbd(C-DOWN)}}} to quite similar effect.
1110 - {{{kbd(M-UP)}}}, {{{kbd(M-DOWN)}}} ::
1114 Move the item including subitems up/down[fn:15], i.e., swap with
1115 previous/next item of same indentation. If the list is ordered,
1116 renumbering is automatic.
1118 - {{{kbd(M-LEFT)}}}, {{{kbd(M-RIGHT)}}} ::
1122 Decrease/increase the indentation of an item, leaving children
1125 - {{{kbd(M-S-LEFT)}}}, {{{kbd(M-S-RIGHT)}}} ::
1129 Decrease/increase the indentation of the item, including subitems.
1130 Initially, the item tree is selected based on current indentation.
1131 When these commands are executed several times in direct succession,
1132 the initially selected region is used, even if the new indentation
1133 would imply a different hierarchy. To use the new hierarchy, break
1134 the command chain by moving point.
1136 As a special case, using this command on the very first item of
1137 a list moves the whole list. This behavior can be disabled by
1138 configuring ~org-list-automatic-rules~. The global indentation of
1139 a list has no influence on the text /after/ the list.
1141 - {{{kbd(C-c C-c)}}} ::
1144 If there is a checkbox (see [[*Checkboxes]]) in the item line, toggle
1145 the state of the checkbox. In any case, verify bullets and
1146 indentation consistency in the whole list.
1148 - {{{kbd(C-c -)}}} ::
1151 #+vindex: org-plain-list-ordered-item-terminator
1152 Cycle the entire list level through the different itemize/enumerate
1153 bullets (=-=, =+=, =*=, =1.=, =1)=) or a subset of them, depending
1154 on ~org-plain-list-ordered-item-terminator~, the type of list, and
1155 its indentation. With a numeric prefix argument N, select the Nth
1156 bullet from this list. If there is an active region when calling
1157 this, selected text is changed into an item. With a prefix
1158 argument, all lines are converted to list items. If the first line
1159 already was a list item, any item marker is removed from the list.
1160 Finally, even without an active region, a normal line is converted
1163 - {{{kbd(C-c *)}}} ::
1166 Turn a plain list item into a headline---so that it becomes
1167 a subheading at its location. See [[*Structure Editing]], for
1168 a detailed explanation.
1170 - {{{kbd(C-c C-*)}}} ::
1173 Turn the whole plain list into a subtree of the current heading.
1174 Checkboxes (see [[*Checkboxes]]) become TODO, respectively DONE,
1175 keywords when unchecked, respectively checked.
1177 - {{{kbd(S-LEFT)}}}, {{{kbd(S-RIGHT)}}} ::
1179 #+vindex: org-support-shift-select
1182 This command also cycles bullet styles when point is in on the
1183 bullet or anywhere in an item line, details depending on
1184 ~org-support-shift-select~.
1186 - {{{kbd(C-c ^)}}} ::
1189 #+cindex: sorting, of plain list
1190 Sort the plain list. Prompt for the sorting method: numerically,
1191 alphabetically, by time, or by custom function.
1195 :DESCRIPTION: Tucking stuff away.
1198 #+cindex: visibility cycling, drawers
1200 Sometimes you want to keep information associated with an entry, but
1201 you normally do not want to see it. For this, Org mode has /drawers/.
1202 They can contain anything but a headline and another drawer. Drawers
1206 ,** This is a headline
1207 Still outside the drawer
1209 This is inside the drawer.
1215 #+findex: org-insert-drawer
1216 You can interactively insert a drawer at point by calling
1217 ~org-insert-drawer~, which is bound to {{{kbd(C-c C-x d)}}}. With an
1218 active region, this command puts the region inside the drawer. With
1219 a prefix argument, this command calls ~org-insert-property-drawer~,
1220 which creates a =PROPERTIES= drawer right below the current headline.
1221 Org mode uses this special drawer for storing properties (see
1222 [[*Properties and Columns]]). You cannot use it for anything else.
1224 Completion over drawer keywords is also possible using
1225 {{{kbd(M-TAB)}}}[fn:16].
1227 Visibility cycling (see [[*Visibility Cycling]]) on the headline hides and
1228 shows the entry, but keep the drawer collapsed to a single line. In
1229 order to look inside the drawer, you need to move point to the drawer
1230 line and press {{{kbd(TAB)}}} there.
1232 You can also arrange for state change notes (see [[Tracking TODO state
1233 changes]]) and clock times (see [[*Clocking Work Time]]) to be stored in
1234 a =LOGBOOK= drawer. If you want to store a quick note there, in
1235 a similar way to state changes, use
1237 - {{{kbd(C-c C-z)}}} ::
1240 Add a time-stamped note to the =LOGBOOK= drawer.
1244 :DESCRIPTION: Folding blocks.
1246 #+vindex: org-hide-block-startup
1247 #+cindex: blocks, folding
1249 Org mode uses =#+BEGIN= ... =#+END= blocks for various purposes from
1250 including source code examples (see [[*Literal Examples]]) to capturing
1251 time logging information (see [[*Clocking Work Time]]). These blocks can
1252 be folded and unfolded by pressing {{{kbd(TAB)}}} in the =#+BEGIN=
1253 line. You can also get all blocks folded at startup by configuring
1254 the variable ~org-hide-block-startup~ or on a per-file basis by using
1256 #+cindex: STARTUP, keyword
1258 ,#+STARTUP: hideblocks
1259 ,#+STARTUP: nohideblocks
1262 ** Creating Footnotes
1264 :DESCRIPTION: How footnotes are defined in Org's syntax.
1268 Org mode supports the creation of footnotes.
1270 A footnote is started by a footnote marker in square brackets in
1271 column 0, no indentation allowed. It ends at the next footnote
1272 definition, headline, or after two consecutive empty lines. The
1273 footnote reference is simply the marker in square brackets, inside
1274 text. Markers always start with =fn:=. For example:
1277 The Org homepage[fn:1] now looks a lot better than it used to.
1279 [fn:1] The link is: https://orgmode.org
1282 Org mode extends the number-based syntax to /named/ footnotes and
1283 optional inline definition. Here are the valid references:
1287 A named footnote reference, where {{{var(NAME)}}} is a unique
1288 label word, or, for simplicity of automatic creation, a number.
1290 - =[fn:: This is the inline definition of this footnote]= ::
1292 An anonymous footnote where the definition is given directly at the
1295 - =[fn:NAME: a definition]= ::
1297 An inline definition of a footnote, which also specifies a name for
1298 the note. Since Org allows multiple references to the same note,
1299 you can then use =[fn:NAME]= to create additional references.
1301 #+vindex: org-footnote-auto-label
1302 Footnote labels can be created automatically, or you can create names
1303 yourself. This is handled by the variable ~org-footnote-auto-label~
1304 and its corresponding =STARTUP= keywords. See the docstring of that
1305 variable for details.
1307 The following command handles footnotes:
1309 - {{{kbd(C-c C-x f)}}} ::
1311 The footnote action command.
1314 When point is on a footnote reference, jump to the definition. When
1315 it is at a definition, jump to the---first---reference.
1317 #+vindex: org-footnote-define-inline
1318 #+vindex: org-footnote-section
1319 Otherwise, create a new footnote. Depending on the variable
1320 ~org-footnote-define-inline~[fn:17], the definition is placed right
1321 into the text as part of the reference, or separately into the
1322 location determined by the variable ~org-footnote-section~.
1324 When this command is called with a prefix argument, a menu of
1325 additional options is offered:
1327 #+attr_texinfo: :columns 0.1 0.9
1328 | {{{kbd(s)}}} | Sort the footnote definitions by reference sequence. |
1329 | {{{kbd(r)}}} | Renumber the simple =fn:N= footnotes. |
1330 | {{{kbd(S)}}} | Short for first {{{kbd(r)}}}, then {{{kbd(s)}}} action. |
1331 | {{{kbd(n)}}} | Rename all footnotes into a =fn:1= ... =fn:n= sequence. |
1332 | {{{kbd(d)}}} | Delete the footnote at point, including definition and references. |
1334 #+vindex: org-footnote-auto-adjust
1335 Depending on the variable ~org-footnote-auto-adjust~[fn:18],
1336 renumbering and sorting footnotes can be automatic after each
1337 insertion or deletion.
1339 - {{{kbd(C-c C-c)}}} ::
1342 If point is on a footnote reference, jump to the definition. If it
1343 is at the definition, jump back to the reference. When called at
1344 a footnote location with a prefix argument, offer the same menu as
1345 {{{kbd(C-c C-x f)}}}.
1347 - {{{kbd(C-c C-o)}}} or {{{kbd(mouse-1/2)}}} ::
1352 Footnote labels are also links to the corresponding definition or
1353 reference, and you can use the usual commands to follow these links.
1357 :DESCRIPTION: Pure magic for quick formatting.
1360 #+cindex: editing tables
1362 Org comes with a fast and intuitive table editor. Spreadsheet-like
1363 calculations are supported using the Emacs Calc package (see [[info:calc][GNU Emacs
1364 Calculator Manual]]).
1366 ** Built-in Table Editor
1368 :DESCRIPTION: Simple tables.
1370 #+cindex: table editor, built-in
1372 #+cindex: header lines, in tables
1373 #+cindex: horizontal rule, in tables
1374 #+cindex: row separator, in tables
1375 #+cindex: table syntax
1376 Org makes it easy to format tables in plain ASCII. Any line with =|=
1377 as the first non-whitespace character is considered part of a table.
1378 =|= is also the column separator[fn:19]. Moreover, a line starting
1379 with =|-= is a horizontal rule. It separates rows explicitely. Rows
1380 before the first horizontal rule are header lines. A table might look
1384 | Name | Phone | Age |
1385 |-------+-------+-----|
1386 | Peter | 1234 | 17 |
1387 | Anna | 4321 | 25 |
1390 A table is re-aligned automatically each time you press
1391 {{{kbd(TAB)}}}, {{{kbd(RET)}}} or {{{kbd(C-c C-c)}}} inside the table.
1392 {{{kbd(TAB)}}} also moves to the next field---{{{kbd(RET)}}} to the
1393 next row---and creates new table rows at the end of the table or
1394 before horizontal lines. The indentation of the table is set by the
1395 first line. Horizontal rules are automatically expanded on every
1396 re-align to span the whole table width. So, to create the above
1397 table, you would only type
1404 #+texinfo: @noindent
1405 and then press {{{kbd(TAB)}}} to align the table and start filling in
1406 fields. Even faster would be to type =|Name|Phone|Age= followed by
1409 When typing text into a field, Org treats {{{kbd(DEL)}}},
1410 {{{kbd(Backspace)}}}, and all character keys in a special way, so that
1411 inserting and deleting avoids shifting other fields. Also, when
1412 typing /immediately/ after point was moved into a new field with
1413 {{{kbd(TAB)}}}, {{{kbd(S-TAB)}}} or {{{kbd(RET)}}}, the field is
1414 automatically made blank. If this behavior is too unpredictable for
1415 you, configure the option ~org-table-auto-blank-field~.
1417 *** Creation and conversion
1422 - {{{kbd(C-c |)}}} (~org-table-create-or-convert-from-region~) ::
1425 #+findex: org-table-create-or-convert-from-region
1426 Convert the active region to table. If every line contains at least
1427 one {{{kbd(TAB)}}} character, the function assumes that the material
1428 is tab separated. If every line contains a comma, comma-separated
1429 values (CSV) are assumed. If not, lines are split at whitespace
1430 into fields. You can use a prefix argument to force a specific
1431 separator: {{{kbd(C-u)}}} forces CSV, {{{kbd(C-u C-u)}}} forces
1432 {{{kbd(TAB)}}}, {{{kbd(C-u C-u C-u)}}} prompts for a regular
1433 expression to match the separator, and a numeric argument
1434 N indicates that at least N consecutive spaces, or alternatively
1435 a {{{kbd(TAB)}}} will be the separator.
1437 If there is no active region, this command creates an empty Org
1438 table. But it is easier just to start typing, like {{{kbd(|
1439 N a m e | P h o n e | A g e RET | - TAB)}}}.
1441 *** Re-aligning and field motion
1446 - {{{kbd(C-c C-c)}}} (~org-table-align~) ::
1449 #+findex: org-table-align
1450 Re-align the table without moving point.
1452 - {{{kbd(TAB)}}} (~org-table-next-field~) ::
1455 #+findex: org-table-next-field
1456 Re-align the table, move to the next field. Creates a new row if
1459 - {{{kbd(C-c SPC)}}} (~org-table-blank-field~) ::
1462 #+findex: org-table-blank-field
1463 Blank the field at point.
1465 - {{{kbd(S-TAB)}}} (~org-table-previous-field~) ::
1468 #+findex: org-table-previous-field
1469 Re-align, move to previous field.
1471 - {{{kbd(RET)}}} (~org-table-next-row~) ::
1474 #+findex: org-table-next-row
1475 Re-align the table and move down to next row. Creates a new row if
1476 necessary. At the beginning or end of a line, {{{kbd(RET)}}} still
1477 inserts a new line, so it can be used to split a table.
1479 - {{{kbd(M-a)}}} (~org-table-beginning-of-field~) ::
1482 #+findex: org-table-beginning-of-field
1483 Move to beginning of the current table field, or on to the previous
1486 - {{{kbd(M-e)}}} (~org-table-end-of-field~) ::
1489 #+findex: org-table-end-of-field
1490 Move to end of the current table field, or on to the next field.
1492 *** Column and row editing
1497 - {{{kbd(M-LEFT)}}} (~org-table-move-column-left~) ::
1500 #+findex: org-table-move-column-left
1501 Move the current column left.
1503 - {{{kbd(M-RIGHT)}}} (~org-table-move-column-right~) ::
1506 #+findex: org-table-move-column-right
1507 Move the current column right.
1509 - {{{kbd(M-S-LEFT)}}} (~org-table-delete-column~) ::
1512 #+findex: org-table-delete-column
1513 Kill the current column.
1515 - {{{kbd(M-S-RIGHT)}}} (~org-table-insert-column~) ::
1518 #+findex: org-table-insert-column
1519 Insert a new column to the left of point position.
1521 - {{{kbd(M-UP)}}} (~org-table-move-row-up~) ::
1524 #+findex: org-table-move-row-up
1525 Move the current row up.
1527 - {{{kbd(M-DOWN)}}} (~org-table-move-row-down~) ::
1530 #+findex: org-table-move-row-down
1531 Move the current row down.
1533 - {{{kbd(M-S-UP)}}} (~org-table-kill-row~) ::
1536 #+findex: org-table-kill-row
1537 Kill the current row or horizontal line.
1539 - {{{kbd(S-UP)}}} (~org-table-move-cell-up~) ::
1542 #+findex: org-table-move-cell-up
1543 Move cell up by swapping with adjacent cell.
1545 - {{{kbd(S-DOWN)}}} (~org-table-move-cell-down~) ::
1548 #+findex: org-table-move-cell-down
1549 Move cell down by swapping with adjacent cell.
1551 - {{{kbd(S-LEFT)}}} (~org-table-move-cell-left~) ::
1554 #+findex: org-table-move-cell-left
1555 Move cell left by swapping with adjacent cell.
1557 - {{{kbd(S-RIGHT)}}} (~org-table-move-cell-right~) ::
1560 #+findex: org-table-move-cell-right
1561 Move cell right by swapping with adjacent cell.
1563 - {{{kbd(M-S-DOWN)}}} (~org-table-insert-row~) ::
1566 #+findex: org-table-insert-row
1567 Insert a new row above the current row. With a prefix argument, the
1568 line is created below the current one.
1570 - {{{kbd(C-c -)}}} (~org-table-insert-hline~) ::
1573 #+findex: org-table-insert-hline
1574 Insert a horizontal line below current row. With a prefix argument,
1575 the line is created above the current line.
1577 - {{{kbd(C-c RET)}}} (~org-table-hline-and-move~) ::
1580 #+findex: org-table-hline-and-move
1581 Insert a horizontal line below current row, and move point into the
1582 row below that line.
1584 - {{{kbd(C-c ^)}}} (~org-table-sort-lines~) ::
1587 #+findex: org-table-sort-lines
1588 Sort the table lines in the region. The position of point indicates
1589 the column to be used for sorting, and the range of lines is the
1590 range between the nearest horizontal separator lines, or the entire
1591 table. If point is before the first column, you are prompted for
1592 the sorting column. If there is an active region, the mark
1593 specifies the first line and the sorting column, while point should
1594 be in the last line to be included into the sorting. The command
1595 prompts for the sorting type, alphabetically, numerically, or by
1596 time. You can sort in normal or reverse order. You can also supply
1597 your own key extraction and comparison functions. When called with
1598 a prefix argument, alphabetic sorting is case-sensitive.
1605 - {{{kbd(C-c C-x M-w)}}} (~org-table-copy-region~) ::
1607 #+kindex: C-c C-x M-w
1608 #+findex: org-table-copy-region
1609 Copy a rectangular region from a table to a special clipboard.
1610 Point and mark determine edge fields of the rectangle. If there is
1611 no active region, copy just the current field. The process ignores
1612 horizontal separator lines.
1614 - {{{kbd(C-c C-x C-w)}}} (~org-table-cut-region~) ::
1616 #+kindex: C-c C-x C-w
1617 #+findex: org-table-cut-region
1618 Copy a rectangular region from a table to a special clipboard, and
1619 blank all fields in the rectangle. So this is the "cut" operation.
1621 - {{{kbd(C-c C-x C-y)}}} (~org-table-paste-rectangle~) ::
1623 #+kindex: C-c C-x C-y
1624 #+findex: org-table-paste-rectangle
1625 Paste a rectangular region into a table. The upper left corner ends
1626 up in the current field. All involved fields are overwritten. If
1627 the rectangle does not fit into the present table, the table is
1628 enlarged as needed. The process ignores horizontal separator lines.
1630 - {{{kbd(M-RET)}}} (~org-table-wrap-region~) ::
1633 #+findex: org-table-wrap-region
1634 Split the current field at point position and move the rest to the
1635 line below. If there is an active region, and both point and mark
1636 are in the same column, the text in the column is wrapped to minimum
1637 width for the given number of lines. A numeric prefix argument may
1638 be used to change the number of desired lines. If there is no
1639 region, but you specify a prefix argument, the current field is made
1640 blank, and the content is appended to the field above.
1647 #+cindex: formula, in tables
1648 #+cindex: calculations, in tables
1650 - {{{kbd(C-c +)}}} (~org-table-sum~) ::
1653 #+findex: org-table-sum
1654 Sum the numbers in the current column, or in the rectangle defined
1655 by the active region. The result is shown in the echo area and can
1656 be inserted with {{{kbd(C-y)}}}.
1658 - {{{kbd(S-RET)}}} (~org-table-copy-down~) ::
1661 #+findex: org-table-copy-down
1662 #+vindex: org-table-copy-increment
1663 When current field is empty, copy from first non-empty field above.
1664 When not empty, copy current field down to next row and move point
1665 along with it. Depending on the variable
1666 ~org-table-copy-increment~, integer field values can be incremented
1667 during copy. Integers that are too large are not incremented,
1668 however. Also, a ~0~ prefix argument temporarily disables the
1669 increment. This key is also used by shift-selection and related
1670 modes (see [[*Packages that conflict with Org mode]]).
1677 - {{{kbd(C-c `)}}} (~org-table-edit-field~) ::
1680 #+findex: org-table-edit-field
1681 Edit the current field in a separate window. This is useful for
1682 fields that are not fully visible (see [[*Column Width and Alignment]]).
1683 When called with a {{{kbd(C-u)}}} prefix, just make the full field
1684 visible, so that it can be edited in place. When called with two
1685 {{{kbd(C-u)}}} prefixes, make the editor window follow point through
1686 the table and always show the current field. The follow mode exits
1687 automatically when point leaves the table, or when you repeat this
1688 command with {{{kbd(C-u C-u C-c `)}}}.
1690 - {{{kbd(M-x org-table-import)}}} ::
1692 #+findex: org-table-import
1693 Import a file as a table. The table should be TAB or whitespace
1694 separated. Use, for example, to import a spreadsheet table or data
1695 from a database, because these programs generally can write
1696 TAB-separated text files. This command works by inserting the file
1697 into the buffer and then converting the region to a table. Any
1698 prefix argument is passed on to the converter, which uses it to
1699 determine the separator.
1701 - {{{kbd(C-c |)}}} (~org-table-create-or-convert-from-region~) ::
1704 #+findex: org-table-create-or-convert-from-region
1705 Tables can also be imported by pasting tabular text into the Org
1706 buffer, selecting the pasted text with {{{kbd(C-x C-x)}}} and then
1707 using the {{{kbd(C-c |)}}} command (see [[*Creation and conversion]]).
1709 - {{{kbd(M-x org-table-export)}}} ::
1711 #+findex: org-table-export
1712 #+vindex: org-table-export-default-format
1713 Export the table, by default as a TAB-separated file. Use for data
1714 exchange with, for example, spreadsheet or database programs. The
1715 format used to export the file can be configured in the variable
1716 ~org-table-export-default-format~. You may also use properties
1717 =TABLE_EXPORT_FILE= and =TABLE_EXPORT_FORMAT= to specify the file
1718 name and the format for table export in a subtree. Org supports
1719 quite general formats for exported tables. The exporter format is
1720 the same as the format used by Orgtbl radio tables, see [[*Translator
1721 functions]], for a detailed description.
1723 ** Column Width and Alignment
1725 :DESCRIPTION: Overrule the automatic settings.
1727 #+cindex: narrow columns in tables
1728 #+cindex: alignment in tables
1730 The width of columns is automatically determined by the table editor.
1731 The alignment of a column is determined automatically from the
1732 fraction of number-like versus non-number fields in the column.
1734 #+vindex: org-table-automatic-realign
1735 Editing a field may modify alignment of the table. Moving
1736 a contiguous row or column---i.e., using {{{kbd(TAB)}}} or
1737 {{{kbd(RET)}}}---automatically re-aligns it. If you want to disable
1738 this behavior, set ~org-table-automatic-realign~ to ~nil~. In any
1739 case, you can always align manually a table:
1741 - {{{kbd(C-c C-c)}}} (~org-table-align~) ::
1744 #+findex: org-table-align
1745 Align the current table.
1747 #+vindex: org-startup-align-all-tables
1748 Setting the option ~org-startup-align-all-tables~ re-aligns all tables
1749 in a file upon visiting it. You can also set this option on
1750 a per-file basis with:
1757 Sometimes a single field or a few fields need to carry more text,
1758 leading to inconveniently wide columns. Maybe you want to hide away
1759 several columns or display them with a fixed width, regardless of
1760 content, as shown in the following example.
1763 |---+---------------------+--------| |---+-------…|…|
1764 | | <6> | | | | <6> …|…|
1765 | 1 | one | some | ----\ | 1 | one …|…|
1766 | 2 | two | boring | ----/ | 2 | two …|…|
1767 | 3 | This is a long text | column | | 3 | This i…|…|
1768 |---+---------------------+--------| |---+-------…|…|
1771 To set the width of a column, one field anywhere in the column may
1772 contain just the string =<N>= where {{{var(N)}}} specifies the width
1773 as a number of characters. You control displayed width of columns
1774 with the following tools:
1776 - {{{kbd(C-c TAB)}}} (~org-table-toggle-column-width~) ::
1779 #+findex: org-table-toggle-column-width
1780 Shrink or expand current column.
1782 If a width cookie specifies a width W for the column, shrinking it
1783 displays the first W visible characters only. Otherwise, the column
1784 is shrunk to a single character.
1786 When called before the first column or after the last one, ask for
1787 a list of column ranges to operate on.
1789 - {{{kbd(C-u C-c TAB)}}} (~org-table-shrink~) ::
1791 #+kindex: C-u C-c TAB
1792 #+findex: org-table-shrink
1793 Shrink all columns with a column width. Expand the others.
1795 - {{{kbd(C-u C-u C-c TAB)}}} (~org-table-expand~) ::
1797 #+kindex: C-u C-u C-c TAB
1798 #+findex: org-table-expand
1801 To see the full text of a shrunk field, hold the mouse over it:
1802 a tool-tip window then shows the full contents of the field.
1803 Alternatively, {{{kbd(C-h .)}}} (~display-local-help~) reveals them,
1804 too. For convenience, any change near the shrunk part of a column
1807 #+vindex: org-startup-shrink-all-tables
1808 Setting the option ~org-startup-shrink-all-tables~ shrinks all columns
1809 containing a width cookie in a file the moment it is visited. You can
1810 also set this option on a per-file basis with:
1814 If you would like to overrule the automatic alignment of number-rich
1815 columns to the right and of string-rich columns to the left, you can
1816 use =<r>=, =<c>= or =<l>= in a similar fashion. You may also combine
1817 alignment and field width like this: =<r10>=.
1819 Lines which only contain these formatting cookies are removed
1820 automatically upon exporting the document.
1824 :DESCRIPTION: Grouping to trigger vertical lines.
1826 #+cindex: grouping columns in tables
1828 When Org exports tables, it does so by default without vertical lines
1829 because that is visually more satisfying in general. Occasionally
1830 however, vertical lines can be useful to structure a table into groups
1831 of columns, much like horizontal lines can do for groups of rows. In
1832 order to specify column groups, you can use a special row where the
1833 first field contains only =/=. The further fields can either contain
1834 =<= to indicate that this column should start a group, =>= to indicate
1835 the end of a column, or =<>= (no space between =<= and =>=) to make
1836 a column a group of its own. Upon export, boundaries between column
1837 groups are marked with vertical lines. Here is an example:
1840 | N | N^2 | N^3 | N^4 | sqrt(n) | sqrt[4](N) |
1841 |---+-----+-----+-----+---------+------------|
1842 | / | < | | > | < | > |
1843 | 1 | 1 | 1 | 1 | 1 | 1 |
1844 | 2 | 4 | 8 | 16 | 1.4142 | 1.1892 |
1845 | 3 | 9 | 27 | 81 | 1.7321 | 1.3161 |
1846 |---+-----+-----+-----+---------+------------|
1847 ,#+TBLFM: $2=$1^2::$3=$1^3::$4=$1^4::$5=sqrt($1)::$6=sqrt(sqrt(($1)))
1850 It is also sufficient to just insert the column group starters after
1851 every vertical line you would like to have:
1854 | N | N^2 | N^3 | N^4 | sqrt(n) | sqrt[4](N) |
1855 |---+-----+-----+-----+---------+------------|
1859 ** The Orgtbl Minor Mode
1861 :DESCRIPTION: The table editor as minor mode.
1862 :ALT_TITLE: Orgtbl Mode
1864 #+cindex: Orgtbl mode
1865 #+cindex: minor mode for tables
1867 #+findex: orgtbl-mode
1868 If you like the intuitive way the Org table editor works, you might
1869 also want to use it in other modes like Text mode or Mail mode. The
1870 minor mode Orgtbl mode makes this possible. You can always toggle the
1871 mode with {{{kbd(M-x orgtbl-mode)}}}. To turn it on by default, for
1872 example in Message mode, use
1874 #+begin_src emacs-lisp
1875 (add-hook 'message-mode-hook 'turn-on-orgtbl)
1878 Furthermore, with some special setup, it is possible to maintain
1879 tables in arbitrary syntax with Orgtbl mode. For example, it is
1880 possible to construct LaTeX tables with the underlying ease and power
1881 of Orgtbl mode, including spreadsheet capabilities. For details, see
1882 [[*Tables in Arbitrary Syntax]].
1886 :DESCRIPTION: The table editor has spreadsheet capabilities.
1888 #+cindex: calculations, in tables
1889 #+cindex: spreadsheet capabilities
1890 #+cindex: Calc package
1892 The table editor makes use of the Emacs Calc package to implement
1893 spreadsheet-like capabilities. It can also evaluate Emacs Lisp forms
1894 to derive fields from other fields. While fully featured, Org's
1895 implementation is not identical to other spreadsheets. For example,
1896 Org knows the concept of a /column formula/ that will be applied to
1897 all non-header fields in a column without having to copy the formula
1898 to each relevant field. There is also a formula debugger, and a
1899 formula editor with features for highlighting fields in the table
1900 corresponding to the references at point in the formula, moving these
1901 references by arrow keys.
1905 :DESCRIPTION: How to refer to another field or range.
1907 #+cindex: references
1909 To compute fields in the table from other fields, formulas must
1910 reference other fields or ranges. In Org, fields can be referenced by
1911 name, by absolute coordinates, and by relative coordinates. To find
1912 out what the coordinates of a field are, press {{{kbd(C-c ?)}}} in
1913 that field, or press {{{kbd(C-c })}}} to toggle the display of a grid.
1915 **** Field references
1920 #+cindex: field references
1921 #+cindex: references, to fields
1922 Formulas can reference the value of another field in two ways. Like
1923 in any other spreadsheet, you may reference fields with
1924 a letter/number combination like =B3=, meaning the second field in the
1925 third row. However, Org prefers to use another, more general
1926 representation that looks like this:[fn:20]
1930 Column specifications can be absolute like =$1=, =$2=, ..., =$N=, or
1931 relative to the current column, i.e., the column of the field which is
1932 being computed, like =$+1= or =$-2=. =$<= and =$>= are immutable
1933 references to the first and last column, respectively, and you can use
1934 =$>>>= to indicate the third column from the right.
1936 The row specification only counts data lines and ignores horizontal
1937 separator lines, or "hlines". Like with columns, you can use absolute
1938 row numbers =@1=, =@2=, ..., =@N=, and row numbers relative to the
1939 current row like =@+3= or =@-1=. =@<= and =@>= are immutable
1940 references the first and last row in the table, respectively. You may
1941 also specify the row relative to one of the hlines: =@I= refers to the
1942 first hline, =@II= to the second, etc. =@-I= refers to the first such
1943 line above the current line, =@+I= to the first such line below the
1944 current line. You can also write =@III+2= which is the second data
1945 line after the third hline in the table.
1947 =@0= and =$0= refer to the current row and column, respectively, i.e.,
1948 to the row/column for the field being computed. Also, if you omit
1949 either the column or the row part of the reference, the current
1950 row/column is implied.
1952 Org's references with /unsigned/ numbers are fixed references in the
1953 sense that if you use the same reference in the formula for two
1954 different fields, the same field is referenced each time. Org's
1955 references with /signed/ numbers are floating references because the
1956 same reference operator can reference different fields depending on
1957 the field being calculated by the formula.
1959 Here are a few examples:
1961 #+attr_texinfo: :columns 0.2 0.8
1962 | =@2$3= | 2nd row, 3rd column (same as =C2=) |
1963 | =$5= | column 5 in the current row (same as =E&=) |
1964 | =@2= | current column, row 2 |
1965 | =@-1$-3= | field one row up, three columns to the left |
1966 | =@-I$2= | field just under hline above current row, column 2 |
1967 | =@>$5= | field in the last row, in column 5 |
1969 **** Range references
1974 #+cindex: range references
1975 #+cindex: references, to ranges
1976 You may reference a rectangular range of fields by specifying two
1977 field references connected by two dots =..=. If both fields are in
1978 the current row, you may simply use =$2..$7=, but if at least one
1979 field is in a different row, you need to use the general =@ROW$COLUMN=
1980 format at least for the first field, i.e., the reference must start
1981 with =@= in order to be interpreted correctly. Examples:
1983 #+attr_texinfo: :columns 0.2 0.8
1984 | =$1..$3= | first three fields in the current row |
1985 | =$P..$Q= | range, using column names (see [[*Advanced features]]) |
1986 | =$<<<..$>>= | start in third column, continue to the last but one |
1987 | =@2$1..@4$3= | six fields between these two fields (same as =A2..C4=) |
1988 | =@-1$-2..@-1= | 3 fields in the row above, starting from 2 columns on the left |
1989 | =@I..II= | between first and second hline, short for =@I..@II= |
1991 #+texinfo: @noindent
1992 Range references return a vector of values that can be fed into Calc
1993 vector functions. Empty fields in ranges are normally suppressed, so
1994 that the vector contains only the non-empty fields. For other options
1995 with the mode switches =E=, =N= and examples, see [[*Formula syntax for
1998 **** Field coordinates in formulas
2003 #+cindex: field coordinates
2004 #+cindex: coordinates, of field
2005 #+cindex: row, of field coordinates
2006 #+cindex: column, of field coordinates
2007 #+vindex: org-table-current-column
2008 #+vindex: org-table-current-dline
2009 One of the very first actions during evaluation of Calc formulas and
2010 Lisp formulas is to substitute =@#= and =$#= in the formula with the
2011 row or column number of the field where the current result will go to.
2012 The traditional Lisp formula equivalents are ~org-table-current-dline~
2013 and ~org-table-current-column~. Examples:
2015 - =if(@# % 2, $#, string(""))= ::
2017 Insert column number on odd rows, set field to empty on even rows.
2019 - =$2 = '(identity remote(FOO, @@#$1))= ::
2021 Copy text or values of each row of column 1 of the table named
2022 {{{var(FOO)}}} into column 2 of the current table.
2024 - =@3 = 2 * remote(FOO, @@1$$#)= ::
2026 Insert the doubled value of each column of row 1 of the table
2027 named {{{var(FOO)}}} into row 3 of the current table.
2029 #+texinfo: @noindent
2030 For the second and third examples, table {{{var(FOO)}}} must have at
2031 least as many rows or columns as the current table. Note that this is
2032 inefficient[fn:21] for large number of rows.
2034 **** Named references
2038 #+cindex: named references
2039 #+cindex: references, named
2040 #+cindex: name, of column or field
2041 #+cindex: constants, in calculations
2042 #+cindex: @samp{CONSTANTS}, keyword
2043 #+vindex: org-table-formula-constants
2045 =$name= is interpreted as the name of a column, parameter or constant.
2046 Constants are defined globally through the variable
2047 ~org-table-formula-constants~, and locally---for the file---through
2048 a line like this example:
2050 : #+CONSTANTS: c=299792458. pi=3.14 eps=2.4e-6
2052 #+vindex: constants-unit-system
2053 #+pindex: constants.el
2054 Also, properties (see [[*Properties and Columns]]) can be used as
2055 constants in table formulas: for a property =Xyz= use the name
2056 =$PROP_Xyz=, and the property will be searched in the current outline
2057 entry and in the hierarchy above it. If you have the =constants.el=
2058 package, it will also be used to resolve constants, including natural
2059 constants like =$h= for Planck's constant, and units like =$km= for
2060 kilometers[fn:22]. Column names and parameters can be specified in
2061 special table lines. These are described below, see [[*Advanced
2062 features]]. All names must start with a letter, and further consist
2063 of letters and numbers.
2065 **** Remote references
2070 #+cindex: remote references
2071 #+cindex: references, remote
2072 #+cindex: references, to a different table
2073 #+cindex: name, of column or field
2074 #+cindex: @samp{NAME}, keyword
2075 You may also reference constants, fields and ranges from a different
2076 table, either in the current file or even in a different file. The
2081 #+texinfo: @noindent
2082 where {{{var(NAME)}}} can be the name of a table in the current file
2083 as set by a =#+NAME:= line before the table. It can also be the ID of
2084 an entry, even in a different file, and the reference then refers to
2085 the first table in that entry. {{{var(REF)}}} is an absolute field or
2086 range reference as described above for example =@3$3= or =$somename=,
2087 valid in the referenced table.
2089 #+cindex: table indirection
2090 When {{{var(NAME)}}} has the format =@ROW$COLUMN=, it is substituted
2091 with the name or ID found in this field of the current table. For
2092 example =remote($1, @@>$2)= \Rightarrow =remote(year_2013, @@>$1)=. The format
2093 =B3= is not supported because it can not be distinguished from a plain
2096 *** Formula syntax for Calc
2098 :DESCRIPTION: Using Calc to compute stuff.
2100 #+cindex: formula syntax, Calc
2101 #+cindex: syntax, of formulas
2103 A formula can be any algebraic expression understood by the Emacs Calc
2104 package. Note that Calc has the non-standard convention that =/= has
2105 lower precedence than =*=, so that =a/b*c= is interpreted as
2106 =(a/(b*c))=. Before evaluation by ~calc-eval~ (see [[info:calc#Calling Calc from Your Programs][Calling Calc from
2107 Your Lisp Programs]]), variable substitution takes place according to
2108 the rules described above.
2110 #+cindex: vectors, in table calculations
2111 The range vectors can be directly fed into the Calc vector functions
2112 like ~vmean~ and ~vsum~.
2114 #+cindex: format specifier, in spreadsheet
2115 #+cindex: mode, for Calc
2116 #+vindex: org-calc-default-modes
2117 A formula can contain an optional mode string after a semicolon. This
2118 string consists of flags to influence Calc and other modes during
2119 execution. By default, Org uses the standard Calc modes (precision
2120 12, angular units degrees, fraction and symbolic modes off). The
2121 display format, however, has been changed to =(float 8)= to keep
2122 tables compact. The default settings can be configured using the
2123 variable ~org-calc-default-modes~.
2127 Set the internal Calc calculation precision to 20 digits.
2129 - =n3=, =s3=, =e2=, =f4= ::
2131 Normal, scientific, engineering or fixed format of the result of
2132 Calc passed back to Org. Calc formatting is unlimited in precision
2133 as long as the Calc calculation precision is greater.
2137 Degree and radian angle modes of Calc.
2141 Fraction and symbolic modes of Calc.
2145 Duration computations in Calc or Lisp, [[*Durations and time values]].
2149 If and how to consider empty fields. Without =E= empty fields in
2150 range references are suppressed so that the Calc vector or Lisp list
2151 contains only the non-empty fields. With =E= the empty fields are
2152 kept. For empty fields in ranges or empty field references the
2153 value =nan= (not a number) is used in Calc formulas and the empty
2154 string is used for Lisp formulas. Add =N= to use 0 instead for both
2155 formula types. For the value of a field the mode =N= has higher
2156 precedence than =E=.
2160 Interpret all fields as numbers, use 0 for non-numbers. See the
2161 next section to see how this is essential for computations with Lisp
2162 formulas. In Calc formulas it is used only occasionally because
2163 there number strings are already interpreted as numbers without =N=.
2167 Literal, for Lisp formulas only. See the next section.
2169 Unless you use large integer numbers or high-precision calculation and
2170 display for floating point numbers you may alternatively provide
2171 a ~printf~ format specifier to reformat the Calc result after it has
2172 been passed back to Org instead of letting Calc already do the
2173 formatting[fn:23]. A few examples:
2175 | =$1+$2= | Sum of first and second field |
2176 | =$1+$2;%.2f= | Same, format result to two decimals |
2177 | =exp($2)+exp($1)= | Math functions can be used |
2178 | =$0;%.1f= | Reformat current cell to 1 decimal |
2179 | =($3-32)*5/9= | Degrees F \to C conversion |
2180 | =$c/$1/$cm= | Hz \to cm conversion, using =constants.el= |
2181 | =tan($1);Dp3s1= | Compute in degrees, precision 3, display SCI 1 |
2182 | =sin($1);Dp3%.1e= | Same, but use ~printf~ specifier for display |
2183 | =vmean($2..$7)= | Compute column range mean, using vector function |
2184 | =vmean($2..$7);EN= | Same, but treat empty fields as 0 |
2185 | =taylor($3,x=7,2)= | Taylor series of $3, at x=7, second degree |
2187 Calc also contains a complete set of logical operations (see [[info:calc#Logical%20Operations][Logical
2188 Operations]]). For example
2190 - =if($1 < 20, teen, string(""))= ::
2192 ="teen"= if age =$1= is less than 20, else the Org table result
2193 field is set to empty with the empty string.
2195 - =if("$1" =​= "nan" || "$2" =​= "nan", string(""), $1 + $2); E f-1= ::
2197 Sum of the first two columns. When at least one of the input fields
2198 is empty the Org table result field is set to empty. =E= is
2199 required to not convert empty fields to 0. =f-1= is an optional
2200 Calc format string similar to =%.1f= but leaves empty results empty.
2202 - =if(typeof(vmean($1..$7)) =​= 12, string(""), vmean($1..$7); E= ::
2204 Mean value of a range unless there is any empty field. Every field
2205 in the range that is empty is replaced by =nan= which lets =vmean=
2206 result in =nan=. Then =typeof == 12= detects the =nan= from ~vmean~
2207 and the Org table result field is set to empty. Use this when the
2208 sample set is expected to never have missing values.
2210 - =if("$1..$7" =​= "[]", string(""), vmean($1..$7))= ::
2212 Mean value of a range with empty fields skipped. Every field in the
2213 range that is empty is skipped. When all fields in the range are
2214 empty the mean value is not defined and the Org table result field
2215 is set to empty. Use this when the sample set can have a variable
2218 - =vmean($1..$7); EN= ::
2220 To complete the example before: Mean value of a range with empty
2221 fields counting as samples with value 0. Use this only when
2222 incomplete sample sets should be padded with 0 to the full size.
2224 You can add your own Calc functions defined in Emacs Lisp with
2225 ~defmath~ and use them in formula syntax for Calc.
2227 *** Emacs Lisp forms as formulas
2229 :DESCRIPTION: Writing formulas in Emacs Lisp.
2230 :ALT_TITLE: Formula syntax for Lisp
2232 #+cindex: Lisp forms, as table formulas
2234 It is also possible to write a formula in Emacs Lisp. This can be
2235 useful for string manipulation and control structures, if Calc's
2236 functionality is not enough.
2238 If a formula starts with a single-quote followed by an opening
2239 parenthesis, then it is evaluated as a Lisp form. The evaluation
2240 should return either a string or a number. Just as with Calc
2241 formulas, you can specify modes and a ~printf~ format after
2244 With Emacs Lisp forms, you need to be conscious about the way field
2245 references are interpolated into the form. By default, a reference is
2246 interpolated as a Lisp string (in double-quotes) containing the field.
2247 If you provide the =N= mode switch, all referenced elements are
2248 numbers---non-number fields will be zero---and interpolated as Lisp
2249 numbers, without quotes. If you provide the =L= flag, all fields are
2250 interpolated literally, without quotes. For example, if you want a
2251 reference to be interpreted as a string by the Lisp form, enclose the
2252 reference operator itself in double-quotes, like ="$3"=. Ranges are
2253 inserted as space-separated fields, so you can embed them in list or
2256 Here are a few examples---note how the =N= mode is used when we do
2257 computations in Lisp:
2259 - ='(concat (substring $1 1 2) (substring $1 0 1) (substring $1 2))= ::
2261 Swap the first two characters of the content of column 1.
2265 Add columns 1 and 2, equivalent to Calc's =$1+$2=.
2267 - ='(apply '+ '($1..$4));N= ::
2269 Compute the sum of columns 1 to 4, like Calc's =vsum($1..$4)=.
2271 *** Durations and time values
2273 :DESCRIPTION: How to compute durations and time values.
2275 #+cindex: duration, computing
2276 #+cindex: time, computing
2277 #+vindex: org-table-duration-custom-format
2279 If you want to compute time values use the =T=, =t=, or =U= flag,
2280 either in Calc formulas or Elisp formulas:
2283 | Task 1 | Task 2 | Total |
2284 |---------+----------+----------|
2285 | 2:12 | 1:47 | 03:59:00 |
2286 | 2:12 | 1:47 | 03:59 |
2287 | 3:02:20 | -2:07:00 | 0.92 |
2288 ,#+TBLFM: @2$3=$1+$2;T::@3$3=$1+$2;U::@4$3=$1+$2;t
2291 Input duration values must be of the form =HH:MM[:SS]=, where seconds
2292 are optional. With the =T= flag, computed durations are displayed as
2293 =HH:MM:SS= (see the first formula above). With the =U= flag, seconds
2294 are omitted so that the result is only =HH:MM= (see second formula
2295 above). Zero-padding of the hours field depends upon the value of the
2296 variable ~org-table-duration-hour-zero-padding~.
2298 With the =t= flag, computed durations are displayed according to the
2299 value of the option ~org-table-duration-custom-format~, which defaults
2300 to ~hours~ and displays the result as a fraction of hours (see the
2301 third formula in the example above).
2303 Negative duration values can be manipulated as well, and integers are
2304 considered as seconds in addition and subtraction.
2306 *** Field and range formulas
2308 :DESCRIPTION: Formula for specific (ranges of) fields.
2310 #+cindex: field formula
2311 #+cindex: range formula
2312 #+cindex: formula, for individual table field
2313 #+cindex: formula, for range of fields
2315 To assign a formula to a particular field, type it directly into the
2316 field, preceded by =:==, for example =vsum(@II..III)=. When you press
2317 {{{kbd(TAB)}}} or {{{kbd(RET)}}} or {{{kbd(C-c C-c)}}} with point
2318 still in the field, the formula is stored as the formula for this
2319 field, evaluated, and the current field is replaced with the result.
2321 #+cindex: @samp{TBLFM}, keyword
2322 Formulas are stored in a special =TBLFM= keyword located directly
2323 below the table. If you type the equation in the fourth field of the
2324 third data line in the table, the formula looks like =@3$4=$1+$2=.
2325 When inserting/deleting/swapping column and rows with the appropriate
2326 commands, /absolute references/ (but not relative ones) in stored
2327 formulas are modified in order to still reference the same field. To
2328 avoid this from happening, in particular in range references, anchor
2329 ranges at the table borders (using =@<=, =@>=, =$<=, =$>=), or at
2330 hlines using the =@I= notation. Automatic adaptation of field
2331 references does not happen if you edit the table structure with normal
2332 editing commands---you must fix the formulas yourself.
2334 Instead of typing an equation into the field, you may also use the
2337 - {{{kbd(C-u C-c =)}}} (~org-table-eval-formula~) ::
2340 #+findex: org-table-eval-formula
2341 Install a new formula for the current field. The command prompts
2342 for a formula with default taken from the =TBLFM= keyword,
2343 applies it to the current field, and stores it.
2345 The left-hand side of a formula can also be a special expression in
2346 order to assign the formula to a number of different fields. There is
2347 no keyboard shortcut to enter such range formulas. To add them, use
2348 the formula editor (see [[*Editing and debugging formulas]]) or edit
2349 the =TBLFM= keyword directly.
2353 Column formula, valid for the entire column. This is so common that
2354 Org treats these formulas in a special way, see [[*Column formulas]].
2358 Row formula, applies to all fields in the specified row. =@>==
2363 Range formula, applies to all fields in the given rectangular range.
2364 This can also be used to assign a formula to some but not all fields
2369 Named field, see [[*Advanced features]].
2373 :DESCRIPTION: Formulas valid for an entire column.
2375 #+cindex: column formula
2376 #+cindex: formula, for table column
2378 When you assign a formula to a simple column reference like =$3==, the
2379 same formula is used in all fields of that column, with the following
2380 very convenient exceptions: (i) If the table contains horizontal
2381 separator hlines with rows above and below, everything before the
2382 first such hline is considered part of the table /header/ and is not
2383 modified by column formulas. Therefore a header is mandatory when you
2384 use column formulas and want to add hlines to group rows, like for
2385 example to separate a total row at the bottom from the summand rows
2386 above. (ii) Fields that already get a value from a field/range
2387 formula are left alone by column formulas. These conditions make
2388 column formulas very easy to use.
2390 To assign a formula to a column, type it directly into any field in
2391 the column, preceded by an equal sign, like ==$1+$2=. When you press
2392 {{{kbd(TAB)}}} or {{{kbd(RET)}}} or {{{kbd(C-c C-c)}}} with point
2393 still in the field, the formula is stored as the formula for the
2394 current column, evaluated and the current field replaced with the
2395 result. If the field contains only ===, the previously stored formula
2396 for this column is used. For each column, Org only remembers the most
2397 recently used formula. In the =TBLFM= keyword, column formulas look
2398 like =$4=$1+$2=. The left-hand side of a column formula can not be
2399 the name of column, it must be the numeric column reference or =$>=.
2401 Instead of typing an equation into the field, you may also use the
2404 - {{{kbd(C-c =)}}} (~org-table-eval-formula~) ::
2407 #+findex: org-table-eval-formula
2408 Install a new formula for the current column and replace current
2409 field with the result of the formula. The command prompts for
2410 a formula, with default taken from the =TBLFM= keyword, applies it
2411 to the current field and stores it. With a numeric prefix argument,
2412 e.g., {{{kbd(C-5 C-c =)}}}, the command applies it to that many
2413 consecutive fields in the current column.
2415 *** Lookup functions
2417 :DESCRIPTION: Lookup functions for searching tables.
2419 #+cindex: lookup functions in tables
2420 #+cindex: table lookup functions
2422 Org has three predefined Emacs Lisp functions for lookups in tables.
2424 - =(org-lookup-first VAL S-LIST R-LIST &optional PREDICATE)= ::
2426 #+findex: org-lookup-first
2427 Searches for the first element {{{var(S)}}} in list
2428 {{{var(S-LIST)}}} for which
2429 #+begin_src emacs-lisp
2432 is non-~nil~; returns the value from the corresponding position in
2433 list {{{var(R-LIST)}}}. The default {{{var(PREDICATE)}}} is
2434 ~equal~. Note that the parameters {{{var(VAL)}}} and {{{var(S)}}}
2435 are passed to {{{var(PREDICATE)}}} in the same order as the
2436 corresponding parameters are in the call to ~org-lookup-first~,
2437 where {{{var(VAL)}}} precedes {{{var(S-LIST)}}}. If
2438 {{{var(R-LIST)}}} is ~nil~, the matching element {{{var(S)}}} of
2439 {{{var(S-LIST)}}} is returned.
2441 - =(org-lookup-last VAL S-LIST R-LIST &optional PREDICATE)= ::
2443 #+findex: org-lookup-last
2444 Similar to ~org-lookup-first~ above, but searches for the /last/
2445 element for which {{{var(PREDICATE)}}} is non-~nil~.
2447 - =(org-lookup-all VAL S-LIST R-LIST &optional PREDICATE)= ::
2449 #+findex: org-lookup-all
2450 Similar to ~org-lookup-first~, but searches for /all/ elements for
2451 which {{{var(PREDICATE)}}} is non-~nil~, and returns /all/
2452 corresponding values. This function can not be used by itself in
2453 a formula, because it returns a list of values. However, powerful
2454 lookups can be built when this function is combined with other Emacs
2457 If the ranges used in these functions contain empty fields, the =E=
2458 mode for the formula should usually be specified: otherwise empty
2459 fields are not included in {{{var(S-LIST)}}} and/or {{{var(R-LIST)}}}
2460 which can, for example, result in an incorrect mapping from an element
2461 of {{{var(S-LIST)}}} to the corresponding element of
2464 These three functions can be used to implement associative arrays,
2465 count matching cells, rank results, group data, etc. For practical
2466 examples see [[https://orgmode.org/worg/org-tutorials/org-lookups.html][this tutorial on Worg]].
2468 *** Editing and debugging formulas
2470 :DESCRIPTION: Fixing formulas.
2472 #+cindex: formula editing
2473 #+cindex: editing, of table formulas
2475 #+vindex: org-table-use-standard-references
2476 You can edit individual formulas in the minibuffer or directly in the
2477 field. Org can also prepare a special buffer with all active formulas
2478 of a table. When offering a formula for editing, Org converts
2479 references to the standard format (like =B3= or =D&=) if possible. If
2480 you prefer to only work with the internal format (like =@3$2= or
2481 =$4=), configure the variable ~org-table-use-standard-references~.
2483 - {{{kbd(C-c =)}}} or {{{kbd(C-u C-c =)}}} (~org-table-eval-formula~) ::
2487 #+findex: org-table-eval-formula
2488 Edit the formula associated with the current column/field in the
2489 minibuffer. See [[*Column formulas]], and [[*Field and range formulas]].
2491 - {{{kbd(C-u C-u C-c =)}}} (~org-table-eval-formula~) ::
2493 #+kindex: C-u C-u C-c =
2494 #+findex: org-table-eval-formula
2495 Re-insert the active formula (either a field formula, or a column
2496 formula) into the current field, so that you can edit it directly in
2497 the field. The advantage over editing in the minibuffer is that you
2498 can use the command {{{kbd(C-c ?)}}}.
2500 - {{{kbd(C-c ?)}}} (~org-table-field-info~) ::
2503 #+findex: org-table-field-info
2504 While editing a formula in a table field, highlight the field(s)
2505 referenced by the reference at point position in the formula.
2507 - {{{kbd(C-c })}}} (~org-table-toggle-coordinate-overlays~) ::
2510 #+findex: org-table-toggle-coordinate-overlays
2511 Toggle the display of row and column numbers for a table, using
2512 overlays. These are updated each time the table is aligned; you can
2513 force it with {{{kbd(C-c C-c)}}}.
2515 - {{{kbd(C-c {)}}} (~org-table-toggle-formula-debugger~) ::
2518 #+findex: org-table-toggle-formula-debugger
2519 Toggle the formula debugger on and off. See below.
2521 - {{{kbd(C-c ')}}} (~org-table-edit-formulas~) ::
2524 #+findex: org-table-edit-formulas
2525 Edit all formulas for the current table in a special buffer, where
2526 the formulas are displayed one per line. If the current field has
2527 an active formula, point in the formula editor marks it. While
2528 inside the special buffer, Org automatically highlights any field or
2529 range reference at point position. You may edit, remove and add
2530 formulas, and use the following commands:
2532 - {{{kbd(C-c C-c)}}} or {{{kbd(C-x C-s)}}} (~org-table-fedit-finish~) ::
2536 #+findex: org-table-fedit-finish
2537 Exit the formula editor and store the modified formulas. With
2538 {{{kbd(C-u)}}} prefix, also apply the new formulas to the
2541 - {{{kbd(C-c C-q)}}} (~org-table-fedit-abort~) ::
2544 #+findex: org-table-fedit-abort
2545 Exit the formula editor without installing changes.
2547 - {{{kbd(C-c C-r)}}} (~org-table-fedit-toggle-ref-type~) ::
2550 #+findex: org-table-fedit-toggle-ref-type
2551 Toggle all references in the formula editor between standard (like
2552 =B3=) and internal (like =@3$2=).
2554 - {{{kbd(TAB)}}} (~org-table-fedit-lisp-indent~) ::
2557 #+findex: org-table-fedit-lisp-indent
2558 Pretty-print or indent Lisp formula at point. When in a line
2559 containing a Lisp formula, format the formula according to Emacs
2560 Lisp rules. Another {{{kbd(TAB)}}} collapses the formula back
2561 again. In the open formula, {{{kbd(TAB)}}} re-indents just like
2564 - {{{kbd(M-TAB)}}} (~lisp-complete-symbol~) ::
2567 #+findex: lisp-complete-symbol
2568 Complete Lisp symbols, just like in Emacs Lisp mode.
2570 - {{{kbd(S-UP)}}}, {{{kbd(S-DOWN)}}}, {{{kbd(S-LEFT)}}}, {{{kbd(S-RIGHT)}}} ::
2576 #+findex: org-table-fedit-ref-up
2577 #+findex: org-table-fedit-ref-down
2578 #+findex: org-table-fedit-ref-left
2579 #+findex: org-table-fedit-ref-right
2580 Shift the reference at point. For example, if the reference is
2581 =B3= and you press {{{kbd(S-RIGHT)}}}, it becomes =C3=. This also
2582 works for relative references and for hline references.
2584 - {{{kbd(M-S-UP)}}} (~org-table-fedit-line-up~) ::
2587 #+findex: org-table-fedit-line-up
2588 Move the test line for column formulas up in the Org buffer.
2590 - {{{kbd(M-S-DOWN)}}} (~org-table-fedit-line-down~) ::
2593 #+findex: org-table-fedit-line-down
2594 Move the test line for column formulas down in the Org buffer.
2596 - {{{kbd(M-UP)}}} (~org-table-fedit-scroll-up~) ::
2599 #+findex: org-table-fedit-scroll-up
2600 Scroll up the window displaying the table.
2602 - {{{kbd(M-DOWN)}}} (~org-table-fedit-scroll-down~) ::
2605 #+findex: org-table-fedit-scroll-down
2606 Scroll down the window displaying the table.
2608 - {{{kbd(C-c })}}} ::
2611 #+findex: org-table-toggle-coordinate-overlays
2612 Turn the coordinate grid in the table on and off.
2614 Making a table field blank does not remove the formula associated with
2615 the field, because that is stored in a different line---the =TBLFM=
2616 keyword line. During the next recalculation, the field will be filled
2617 again. To remove a formula from a field, you have to give an empty
2618 reply when prompted for the formula, or to edit the =TBLFM= keyword.
2621 You may edit the =TBLFM= keyword directly and re-apply the changed
2622 equations with {{{kbd(C-c C-c)}}} in that line or with the normal
2623 recalculation commands in the table.
2625 **** Using multiple =TBLFM= lines
2629 #+cindex: multiple formula lines
2630 #+cindex: @samp{TBLFM} keywords, multiple
2631 #+cindex: @samp{TBLFM}, switching
2634 You may apply the formula temporarily. This is useful when you want
2635 to switch the formula applied to the table. Place multiple =TBLFM=
2636 keywords right after the table, and then press {{{kbd(C-c C-c)}}} on
2637 the formula to apply. Here is an example:
2648 #+texinfo: @noindent
2649 Pressing {{{kbd(C-c C-c)}}} in the line of =#+TBLFM: $2=$1*2= yields:
2660 #+texinfo: @noindent
2661 If you recalculate this table, with {{{kbd(C-u C-c *)}}}, for example,
2662 you get the following result from applying only the first =TBLFM=
2674 **** Debugging formulas
2678 #+cindex: formula debugging
2679 #+cindex: debugging, of table formulas
2681 When the evaluation of a formula leads to an error, the field content
2682 becomes the string =#ERROR=. If you would like to see what is going
2683 on during variable substitution and calculation in order to find
2684 a bug, turn on formula debugging in the Tbl menu and repeat the
2685 calculation, for example by pressing {{{kbd(C-u C-u C-c = RET)}}} in
2686 a field. Detailed information are displayed.
2688 *** Updating the table
2690 :DESCRIPTION: Recomputing all dependent fields.
2692 #+cindex: recomputing table fields
2693 #+cindex: updating, table
2695 Recalculation of a table is normally not automatic, but needs to be
2696 triggered by a command. To make recalculation at least
2697 semi-automatic, see [[*Advanced features]].
2699 In order to recalculate a line of a table or the entire table, use the
2702 - {{{kbd(C-c *)}}} (~org-table-recalculate~) ::
2705 #+findex: org-table-recalculate
2706 Recalculate the current row by first applying the stored column
2707 formulas from left to right, and all field/range formulas in the
2710 - {{{kbd(C-u C-c *)}}} or {{{kbd(C-u C-c C-c)}}} ::
2713 #+kindex: C-u C-c C-c
2714 Recompute the entire table, line by line. Any lines before the
2715 first hline are left alone, assuming that these are part of the
2718 - {{{kbd(C-u C-u C-c *)}}} or {{{kbd(C-u C-u C-c C-c)}}} (~org-table-iterate~) ::
2720 #+kindex: C-u C-u C-c *
2721 #+kindex: C-u C-u C-c C-c
2722 #+findex: org-table-iterate
2723 Iterate the table by recomputing it until no further changes occur.
2724 This may be necessary if some computed fields use the value of other
2725 fields that are computed /later/ in the calculation sequence.
2727 - {{{kbd(M-x org-table-recalculate-buffer-tables)}}} ::
2729 #+findex: org-table-recalculate-buffer-tables
2730 Recompute all tables in the current buffer.
2732 - {{{kbd(M-x org-table-iterate-buffer-tables)}}} ::
2734 #+findex: org-table-iterate-buffer-tables
2735 Iterate all tables in the current buffer, in order to converge
2736 table-to-table dependencies.
2738 *** Advanced features
2740 :DESCRIPTION: Field and column names, automatic recalculation...
2743 If you want the recalculation of fields to happen automatically, or if
2744 you want to be able to assign /names/[fn:24] to fields and columns,
2745 you need to reserve the first column of the table for special marking
2748 - {{{kbd(C-#)}}} (~org-table-rotate-recalc-marks~) ::
2751 #+findex: org-table-rotate-recalc-marks
2752 Rotate the calculation mark in first column through the states =#=,
2753 =*=, =!=, =$=. When there is an active region, change all marks in
2756 Here is an example of a table that collects exam results of students
2757 and makes use of these features:
2760 |---+---------+--------+--------+--------+-------+------|
2761 | | Student | Prob 1 | Prob 2 | Prob 3 | Total | Note |
2762 |---+---------+--------+--------+--------+-------+------|
2763 | ! | | P1 | P2 | P3 | Tot | |
2764 | # | Maximum | 10 | 15 | 25 | 50 | 10.0 |
2765 | ^ | | m1 | m2 | m3 | mt | |
2766 |---+---------+--------+--------+--------+-------+------|
2767 | # | Peter | 10 | 8 | 23 | 41 | 8.2 |
2768 | # | Sam | 2 | 4 | 3 | 9 | 1.8 |
2769 |---+---------+--------+--------+--------+-------+------|
2770 | | Average | | | | 25.0 | |
2771 | ^ | | | | | at | |
2772 | $ | max=50 | | | | | |
2773 |---+---------+--------+--------+--------+-------+------|
2774 ,#+TBLFM: $6=vsum($P1..$P3)::$7=10*$Tot/$max;%.1f::$at=vmean(@-II..@-I);%.1f
2777 #+attr_texinfo: :tag Important
2779 Please note that for these special tables, recalculating the table
2780 with {{{kbd(C-u C-c *)}}} only affects rows that are marked =#= or
2781 =*=, and fields that have a formula assigned to the field itself. The
2782 column formulas are not applied in rows with empty first field.
2785 #+cindex: marking characters, tables
2786 The marking characters have the following meaning:
2790 The fields in this line define names for the columns, so that you
2791 may refer to a column as =$Tot= instead of =$6=.
2795 This row defines names for the fields /above/ the row. With such
2796 a definition, any formula in the table may use =$m1= to refer to the
2797 value =10=. Also, if you assign a formula to a names field, it is
2798 stored as =$name = ...=.
2802 Similar to =^=, but defines names for the fields in the row /below/.
2806 Fields in this row can define /parameters/ for formulas. For
2807 example, if a field in a =$= row contains =max=50=, then formulas in
2808 this table can refer to the value 50 using =$max=. Parameters work
2809 exactly like constants, only that they can be defined on a per-table
2814 Fields in this row are automatically recalculated when pressing
2815 {{{kbd(TAB)}}} or {{{kbd(RET)}}} or {{{kbd(S-TAB)}}} in this row.
2816 Also, this row is selected for a global recalculation with
2817 {{{kbd(C-u C-c *)}}}. Unmarked lines are left alone by this
2822 Selects this line for global recalculation with {{{kbd(C-u C-c
2823 *)}}}, but not for automatic recalculation. Use this when automatic
2824 recalculation slows down editing too much.
2828 Do not export this line. Useful for lines that contain the
2829 narrowing =<N>= markers or column group markers.
2831 Finally, just to whet your appetite for what can be done with the
2832 fantastic Calc package, here is a table that computes the Taylor
2833 series of degree n at location x for a couple of functions.
2836 |---+-------------+---+-----+--------------------------------------|
2837 | | Func | n | x | Result |
2838 |---+-------------+---+-----+--------------------------------------|
2839 | # | exp(x) | 1 | x | 1 + x |
2840 | # | exp(x) | 2 | x | 1 + x + x^2 / 2 |
2841 | # | exp(x) | 3 | x | 1 + x + x^2 / 2 + x^3 / 6 |
2842 | # | x^2+sqrt(x) | 2 | x=0 | x*(0.5 / 0) + x^2 (2 - 0.25 / 0) / 2 |
2843 | # | x^2+sqrt(x) | 2 | x=1 | 2 + 2.5 x - 2.5 + 0.875 (x - 1)^2 |
2844 | * | tan(x) | 3 | x | 0.0175 x + 1.77e-6 x^3 |
2845 |---+-------------+---+-----+--------------------------------------|
2846 ,#+TBLFM: $5=taylor($2,$4,$3);n3
2851 :DESCRIPTION: Plotting from Org tables.
2853 #+cindex: graph, in tables
2854 #+cindex: plot tables using Gnuplot
2856 Org Plot can produce graphs of information stored in Org tables,
2857 either graphically or in ASCII art.
2859 *** Graphical plots using Gnuplot
2864 #+cindex: @samp{PLOT}, keyword
2865 Org Plot can produce 2D and 3D graphs of information stored in Org
2866 tables using [[http://www.gnuplot.info/][Gnuplot]] and [[http://cars9.uchicago.edu/~ravel/software/gnuplot-mode.html][Gnuplot mode]]. To see this in action, ensure
2867 that you have both Gnuplot and Gnuplot mode installed on your system,
2868 then call {{{kbd(C-c \quot g)}}} or {{{kbd(M-x org-plot/gnuplot)}}} on the
2872 ,#+PLOT: title:"Citas" ind:1 deps:(3) type:2d with:histograms set:"yrange [0:]"
2873 | Sede | Max cites | H-index |
2874 |-----------+-----------+---------|
2875 | Chile | 257.72 | 21.39 |
2876 | Leeds | 165.77 | 19.68 |
2877 | Sao Paolo | 71.00 | 11.50 |
2878 | Stockholm | 134.19 | 14.33 |
2879 | Morelia | 257.56 | 17.67 |
2882 Notice that Org Plot is smart enough to apply the table's headers as
2883 labels. Further control over the labels, type, content, and
2884 appearance of plots can be exercised through the =PLOT= keyword
2885 preceding a table. See below for a complete list of Org Plot options.
2886 For more information and examples see the [[https://orgmode.org/worg/org-tutorials/org-plot.html][Org Plot tutorial]].
2895 Specify any Gnuplot option to be set when graphing.
2899 Specify the title of the plot.
2903 Specify which column of the table to use as the =x= axis.
2907 Specify the columns to graph as a Lisp style list, surrounded by
2908 parentheses and separated by spaces for example =dep:(3 4)= to graph
2909 the third and fourth columns. Defaults to graphing all other
2910 columns aside from the =ind= column.
2914 Specify whether the plot is =2d=, =3d=, or =grid=.
2918 Specify a =with= option to be inserted for every column being
2919 plotted, e.g., =lines=, =points=, =boxes=, =impulses=. Defaults to
2924 If you want to plot to a file, specify
2925 ="path/to/desired/output-file"=.
2929 List of labels to be used for the =deps=. Defaults to the column
2930 headers if they exist.
2934 Specify an entire line to be inserted in the Gnuplot script.
2938 When plotting =3d= or =grid= types, set this to =t= to graph a flat
2939 mapping rather than a =3d= slope.
2943 Specify format of Org mode timestamps as they will be parsed by
2944 Gnuplot. Defaults to =%Y-%m-%d-%H:%M:%S=.
2948 If you want total control, you can specify a script file---place the
2949 file name between double-quotes---which will be used to plot.
2950 Before plotting, every instance of =$datafile= in the specified
2951 script will be replaced with the path to the generated data file.
2952 Note: even if you set this option, you may still want to specify the
2953 plot type, as that can impact the content of the data file.
2960 While point is on a column, typing {{{kbd(C-c " a)}}} or {{{kbd(M-x
2961 orgtbl-ascii-plot)}}} create a new column containing an ASCII-art bars
2962 plot. The plot is implemented through a regular column formula. When
2963 the source column changes, the bar plot may be updated by refreshing
2964 the table, for example typing {{{kbd(C-u C-c *)}}}.
2967 | Sede | Max cites | |
2968 |---------------+-----------+--------------|
2969 | Chile | 257.72 | WWWWWWWWWWWW |
2970 | Leeds | 165.77 | WWWWWWWh |
2971 | Sao Paolo | 71.00 | WWW; |
2972 | Stockholm | 134.19 | WWWWWW: |
2973 | Morelia | 257.56 | WWWWWWWWWWWH |
2974 | Rochefourchat | 0.00 | |
2975 ,#+TBLFM: $3='(orgtbl-ascii-draw $2 0.0 257.72 12)
2978 The formula is an Elisp call.
2980 #+attr_texinfo: :options orgtbl-ascii-draw value min max &optional width
2982 Draw an ASCII bar in a table.
2984 {{{var(VALUE)}}} is the value to plot.
2986 {{{var(MIN)}}} is the value displayed as an empty bar. {{{var(MAX)}}}
2987 is the value filling all the {{{var(WIDTH)}}}. Sources values outside
2988 this range are displayed as =too small= or =too large=.
2990 {{{var(WIDTH)}}} is the number of characters of the bar plot. It
2996 :DESCRIPTION: Notes in context.
2998 #+cindex: hyperlinks
3000 Like HTML, Org provides support for links inside a file, external
3001 links to other files, Usenet articles, emails, and much more.
3005 :DESCRIPTION: How links in Org are formatted.
3007 #+cindex: link format
3008 #+cindex: format, of links
3010 #+cindex: angle bracket links
3011 #+cindex: plain links
3012 Org recognizes plain URIs, possibly wrapped within angle
3013 brackets[fn:25], and activate them as clickable links.
3015 #+cindex: bracket links
3016 The general link format, however, looks like this:
3018 : [[LINK][DESCRIPTION]]
3020 #+texinfo: @noindent
3025 #+cindex: square brackets in links
3026 #+cindex: escape syntax, for links
3027 The {{{var(LINK)}}} part cannot contain =[= and =]= characters. You
3028 can replace them with their percent-encoded counterparts, which are,
3029 respectively, =%5B= and =%5D=. You also need to encode =%= characters
3030 as =%25=. Optionally, it may also come handy to encode consecutive
3033 Org takes for granted that such links are correctly escaped. Luckily,
3034 functions inserting links (see [[*Handling Links]]) take care of this.
3035 You really need to bother about it only when inserting manually a URI
3036 within square brackets.
3038 Once a link in the buffer is complete, with all brackets present, Org
3039 changes the display so that =DESCRIPTION= is displayed instead of
3040 =[[LINK][DESCRIPTION]]= and =LINK= is displayed instead of =[[LINK]]=.
3041 Links are highlighted in the ~org-link~ face, which, by default, is an
3044 You can directly edit the visible part of a link. This can be either
3045 the {{{var(LINK)}}} part, if there is no description, or the
3046 {{{var(DESCRIPTION)}}} part otherwise. To also edit the invisible
3047 {{{var(LINK)}}} part, use {{{kbd(C-c C-l)}}} with point on the link
3048 (see [[*Handling Links]]).
3050 If you place point at the beginning or just behind the end of the
3051 displayed text and press {{{kbd(BS)}}}, you remove
3052 the---invisible---bracket at that location[fn:26]. This makes the link
3053 incomplete and the internals are again displayed as plain text.
3054 Inserting the missing bracket hides the link internals again. To show
3055 the internal structure of all links, use the menu: Org \rarr Hyperlinks \rarr
3060 :DESCRIPTION: Links to other places in the current file.
3062 #+cindex: internal links
3063 #+cindex: links, internal
3064 #+cindex: targets, for links
3066 #+cindex: @samp{CUSTOM_ID}, property
3067 If the link does not look like a URL, it is considered to be internal
3068 in the current file. The most important case is a link like
3069 =[[#my-custom-id]]= which links to the entry with the =CUSTOM_ID= property
3070 =my-custom-id=. You are responsible yourself to make sure these
3071 custom IDs are unique in a file.
3073 Links such as =[[My Target]]= or =[[My Target][Find my target]]= lead to a text search in
3076 The link can be followed with {{{kbd(C-c C-o)}}} when point is on
3077 the link, or with a mouse click (see [[*Handling Links]]). Links to
3078 custom IDs point to the corresponding headline. The preferred match
3079 for a text link is a /dedicated target/: the same string in double
3080 angular brackets, like =<<My Target>>=.
3082 #+cindex: @samp{NAME}, keyword
3083 If no dedicated target exists, the link tries to match the exact name
3084 of an element within the buffer. Naming is done with the =NAME=
3085 keyword, which has to be put in the line before the element it refers
3086 to, as in the following example
3095 If none of the above succeeds, Org searches for a headline that is
3096 exactly the link text but may also include a TODO keyword and
3099 During export, internal links are used to mark objects and assign them
3100 a number. Marked objects are then referenced by links pointing to
3101 them. In particular, links without a description appear as the number
3102 assigned to the marked object[fn:28]. In the following excerpt from
3107 2. <<target>>another item
3108 Here we refer to item [[target]].
3111 #+texinfo: @noindent
3112 The last sentence will appear as =Here we refer to item 2= when
3115 In non-Org files, the search looks for the words in the link text. In
3116 the above example the search would be for =target=.
3118 Following a link pushes a mark onto Org's own mark ring. You can
3119 return to the previous position with {{{kbd(C-c &)}}}. Using this
3120 command several times in direct succession goes back to positions
3125 :DESCRIPTION: Make targets trigger links in plain text.
3127 #+cindex: radio targets
3128 #+cindex: targets, radio
3129 #+cindex: links, radio targets
3131 Org can automatically turn any occurrences of certain target names in
3132 normal text into a link. So without explicitly creating a link, the
3133 text connects to the target radioing its position. Radio targets are
3134 enclosed by triple angular brackets. For example, a target =<<<My
3135 Target>>>= causes each occurrence of =my target= in normal text to
3136 become activated as a link. The Org file is scanned automatically for
3137 radio targets only when the file is first loaded into Emacs. To
3138 update the target list during editing, press {{{kbd(C-c C-c)}}} with
3139 point on or at a target.
3143 :DESCRIPTION: URL-like links to the world.
3145 #+cindex: links, external
3146 #+cindex: external links
3147 #+cindex: Gnus links
3148 #+cindex: BBDB links
3151 #+cindex: file links
3152 #+cindex: Rmail links
3153 #+cindex: MH-E links
3154 #+cindex: Usenet links
3155 #+cindex: shell links
3156 #+cindex: Info links
3157 #+cindex: Elisp links
3159 Org supports links to files, websites, Usenet and email messages, BBDB
3160 database entries and links to both IRC conversations and their logs.
3161 External links are URL-like locators. They start with a short
3162 identifying string followed by a colon. There can be no space after
3163 the colon. The following list shows examples for each link type.
3165 | =http://www.astro.uva.nl/=dominik= | on the web |
3166 | =doi:10.1000/182= | DOI for an electronic resource |
3167 | =file:/home/dominik/images/jupiter.jpg= | file, absolute path |
3168 | =/home/dominik/images/jupiter.jpg= | same as above |
3169 | =file:papers/last.pdf= | file, relative path |
3170 | =./papers/last.pdf= | same as above |
3171 | =file:/ssh:me@some.where:papers/last.pdf= | file, path on remote machine |
3172 | =/ssh:me@some.where:papers/last.pdf= | same as above |
3173 | =file:sometextfile::NNN= | file, jump to line number |
3174 | =file:projects.org= | another Org file |
3175 | =file:projects.org::some words= | text search in Org file[fn:29] |
3176 | =file:projects.org::*task title= | heading search in Org file |
3177 | =file+sys:/path/to/file= | open via OS, like double-click |
3178 | =file+emacs:/path/to/file= | force opening by Emacs |
3179 | =docview:papers/last.pdf::NNN= | open in doc-view mode at page |
3180 | =id:B7423F4D-2E8A-471B-8810-C40F074717E9= | link to heading by ID |
3181 | =news:comp.emacs= | Usenet link |
3182 | =mailto:adent@galaxy.net= | mail link |
3183 | =mhe:folder= | MH-E folder link |
3184 | =mhe:folder#id= | MH-E message link |
3185 | =rmail:folder= | Rmail folder link |
3186 | =rmail:folder#id= | Rmail message link |
3187 | =gnus:group= | Gnus group link |
3188 | =gnus:group#id= | Gnus article link |
3189 | =bbdb:R.*Stallman= | BBDB link (with regexp) |
3190 | =irc:/irc.com/#emacs/bob= | IRC link |
3191 | =info:org#External links= | Info node link |
3192 | =shell:ls *.org= | shell command |
3193 | =elisp:org-agenda= | interactive Elisp command |
3194 | =elisp:(find-file "Elisp.org")= | Elisp form to evaluate |
3197 #+cindex: Wanderlust links
3198 On top of these built-in link types, additional ones are available
3199 through the =contrib/= directory (see [[*Installation]]). For example,
3200 these links to VM or Wanderlust messages are available when you load
3201 the corresponding libraries from the =contrib/= directory:
3203 | =vm:folder= | VM folder link |
3204 | =vm:folder#id= | VM message link |
3205 | =vm://myself@some.where.org/folder#id= | VM on remote machine |
3206 | =vm-imap:account:folder= | VM IMAP folder link |
3207 | =vm-imap:account:folder#id= | VM IMAP message link |
3208 | =wl:folder= | Wanderlust folder link |
3209 | =wl:folder#id= | Wanderlust message link |
3211 For information on customizing Org to add new link types, see [[*Adding
3214 A link should be enclosed in double brackets and may contain
3215 descriptive text to be displayed instead of the URL (see [[*Link
3216 Format]]), for example:
3218 : [[http://www.gnu.org/software/emacs/][GNU Emacs]]
3220 If the description is a file name or URL that points to an image, HTML
3221 export (see [[*HTML Export]]) inlines the image as a clickable button. If
3222 there is no description at all and the link points to an image, that
3223 image is inlined into the exported HTML file.
3225 #+cindex: square brackets, around links
3226 #+cindex: angular brackets, around links
3227 #+cindex: plain text external links
3228 Org also finds external links in the normal text and activates them as
3229 links. If spaces must be part of the link (for example in
3230 =bbdb:Richard Stallman=), or if you need to remove ambiguities about
3231 the end of the link, enclose the link in square or angular brackets.
3235 :DESCRIPTION: Creating, inserting and following.
3237 #+cindex: links, handling
3239 Org provides methods to create a link in the correct syntax, to insert
3240 it into an Org file, and to follow the link.
3242 #+findex: org-store-link
3243 #+cindex: storing links
3244 The main function is ~org-store-link~, called with {{{kbd(M-x
3245 org-store-link)}}}. Because of its importance, we suggest to bind it
3246 to a widely available key (see [[*Activation]]). It stores a link to the
3247 current location. The link is stored for later insertion into an Org
3248 buffer---see below. The kind of link that is created depends on the
3251 - /Org mode buffers/ ::
3253 For Org files, if there is a =<<target>>= at point, the link points
3254 to the target. Otherwise it points to the current headline, which
3255 is also the description[fn:30].
3257 #+vindex: org-link-to-org-use-id
3258 #+cindex: @samp{CUSTOM_ID}, property
3259 #+cindex: @samp{ID}, property
3260 If the headline has a =CUSTOM_ID= property, store a link to this
3261 custom ID. In addition or alternatively, depending on the value of
3262 ~org-link-to-org-use-id~, create and/or use a globally unique =ID=
3263 property for the link[fn:31]. So using this command in Org buffers
3264 potentially creates two links: a human-readable link from the custom
3265 ID, and one that is globally unique and works even if the entry is
3266 moved from file to file. Later, when inserting the link, you need
3267 to decide which one to use.
3269 - /Email/News clients: VM, Rmail, Wanderlust, MH-E, Gnus/ ::
3271 #+vindex: org-email-link-description-format
3272 Pretty much all Emacs mail clients are supported. The link points
3273 to the current article, or, in some Gnus buffers, to the group. The
3274 description is constructed according to the variable
3275 ~org-email-link-description-format~. By default, it refers to the
3276 addressee and the subject.
3278 - /Web browsers: W3, W3M and EWW/ ::
3280 Here the link is the current URL, with the page title as the
3283 - /Contacts: BBDB/ ::
3285 Links created in a BBDB buffer point to the current entry.
3289 #+vindex: org-irc-links-to-logs
3290 For IRC links, if the variable ~org-irc-link-to-logs~ is non-~nil~,
3291 create a =file= style link to the relevant point in the logs for the
3292 current conversation. Otherwise store an =irc= style link to the
3293 user/channel/server under the point.
3297 For any other file, the link points to the file, with a search
3298 string (see [[*Search Options in File Links]]) pointing to the contents
3299 of the current line. If there is an active region, the selected
3300 words form the basis of the search string. You can write custom Lisp
3301 functions to select the search string and perform the search for
3302 particular file types (see [[*Custom Searches]]).
3304 You can also define dedicated links to other files. See [[*Adding
3309 When point is in an agenda view, the created link points to the
3310 entry referenced by the current line.
3312 From an Org buffer, the following commands create, navigate or, more
3313 generally, act on links.
3315 #+attr_texinfo: :sep ,
3316 - {{{kbd(C-c C-l)}}} (~org-insert-link~) ::
3319 #+findex: org-insert-link
3320 #+cindex: link completion
3321 #+cindex: completion, of links
3322 #+cindex: inserting links
3323 #+vindex: org-keep-stored-link-after-insertion
3324 Insert a link[fn:32]. This prompts for a link to be inserted into
3325 the buffer. You can just type a link, using text for an internal
3326 link, or one of the link type prefixes mentioned in the examples
3327 above. The link is inserted into the buffer, along with
3328 a descriptive text[fn:33]. If some text was selected at this time,
3329 it becomes the default description.
3331 - /Inserting stored links/ ::
3333 All links stored during the current session are part of the
3334 history for this prompt, so you can access them with {{{kbd(UP)}}}
3335 and {{{kbd(DOWN)}}} (or {{{kbd(M-p)}}}, {{{kbd(M-n)}}}).
3337 - /Completion support/ ::
3339 Completion with {{{kbd(TAB)}}} helps you to insert valid link
3340 prefixes like =http= or =ftp=, including the prefixes defined
3341 through link abbreviations (see [[*Link Abbreviations]]). If you
3342 press {{{kbd(RET)}}} after inserting only the prefix, Org offers
3343 specific completion support for some link types[fn:34]. For
3344 example, if you type {{{kbd(f i l e RET)}}}---alternative access:
3345 {{{kbd(C-u C-c C-l)}}}, see below---Org offers file name
3346 completion, and after {{{kbd(b b d b RET)}}} you can complete
3349 - {{{kbd(C-u C-c C-l)}}} ::
3351 #+cindex: file name completion
3352 #+cindex: completion, of file names
3353 #+kindex: C-u C-c C-l
3354 When {{{kbd(C-c C-l)}}} is called with a {{{kbd(C-u)}}} prefix
3355 argument, insert a link to a file. You may use file name completion
3356 to select the name of the file. The path to the file is inserted
3357 relative to the directory of the current Org file, if the linked
3358 file is in the current directory or in a sub-directory of it, or if
3359 the path is written relative to the current directory using =../=.
3360 Otherwise an absolute path is used, if possible with =~/= for your
3361 home directory. You can force an absolute path with two
3362 {{{kbd(C-u)}}} prefixes.
3364 - {{{kbd(C-c C-l)}}} (with point on existing link) ::
3366 #+cindex: following links
3367 When point is on an existing link, {{{kbd(C-c C-l)}}} allows you to
3368 edit the link and description parts of the link.
3370 - {{{kbd(C-c C-o)}}} (~org-open-at-point~) ::
3373 #+findex: org-open-at-point
3374 #+vindex: org-file-apps
3375 Open link at point. This launches a web browser for URL (using
3376 ~browse-url-at-point~), run VM/MH-E/Wanderlust/Rmail/Gnus/BBDB for
3377 the corresponding links, and execute the command in a shell link.
3378 When point is on an internal link, this command runs the
3379 corresponding search. When point is on the tags part of a headline,
3380 it creates the corresponding tags view (see [[*Matching tags and
3381 properties]]). If point is on a timestamp, it compiles the agenda for
3382 that date. Furthermore, it visits text and remote files in =file=
3383 links with Emacs and select a suitable application for local
3384 non-text files. Classification of files is based on file extension
3385 only. See option ~org-file-apps~. If you want to override the
3386 default application and visit the file with Emacs, use
3387 a {{{kbd(C-u)}}} prefix. If you want to avoid opening in Emacs, use
3388 a {{{kbd(C-u C-u)}}} prefix.
3390 #+vindex: org-link-frame-setup
3391 If point is on a headline, but not on a link, offer all links in the
3392 headline and entry text. If you want to setup the frame
3393 configuration for following links, customize ~org-link-frame-setup~.
3397 #+vindex: org-return-follows-link
3399 When ~org-return-follows-link~ is set, {{{kbd(RET)}}} also follows
3402 - {{{kbd(mouse-2)}}} or {{{kbd(mouse-1)}}} ::
3406 On links, {{{kbd(mouse-1)}}} and {{{kbd(mouse-2)}}} opens the link
3407 just as {{{kbd(C-c C-o)}}} does.
3409 - {{{kbd(mouse-3)}}} ::
3411 #+vindex: org-display-internal-link-with-indirect-buffer
3413 Like {{{kbd(mouse-2)}}}, but force file links to be opened with
3414 Emacs, and internal links to be displayed in another window[fn:35].
3416 - {{{kbd(C-c %)}}} (~org-mark-ring-push~) ::
3419 #+findex: org-mark-ring-push
3421 Push the current position onto the Org mark ring, to be able to
3422 return easily. Commands following an internal link do this
3425 - {{{kbd(C-c &)}}} (~org-mark-ring-goto~) ::
3428 #+findex: org-mark-ring-goto
3429 #+cindex: links, returning to
3430 Jump back to a recorded position. A position is recorded by the
3431 commands following internal links, and by {{{kbd(C-c %)}}}. Using
3432 this command several times in direct succession moves through a ring
3433 of previously recorded positions.
3435 - {{{kbd(C-c C-x C-n)}}} (~org-next-link~), {{{kbd(C-c C-x C-p)}}} (~org-previous-link~) ::
3437 #+kindex: C-c C-x C-p
3438 #+findex: org-previous-link
3439 #+kindex: C-c C-x C-n
3440 #+findex: org-next-link
3441 #+cindex: links, finding next/previous
3442 Move forward/backward to the next link in the buffer. At the limit
3443 of the buffer, the search fails once, and then wraps around. The
3444 key bindings for this are really too long; you might want to bind
3445 this also to {{{kbd(M-n)}}} and {{{kbd(M-p)}}}.
3447 #+begin_src emacs-lisp
3448 (add-hook 'org-load-hook
3450 (define-key org-mode-map "\M-n" 'org-next-link)
3451 (define-key org-mode-map "\M-p" 'org-previous-link)))
3454 ** Using Links Outside Org
3456 :DESCRIPTION: Linking from my C source code?
3459 #+findex: org-insert-link-global
3460 #+findex: org-open-at-point-global
3461 You can insert and follow links that have Org syntax not only in Org,
3462 but in any Emacs buffer. For this, Org provides two functions:
3463 ~org-insert-link-global~ and ~org-open-at-point-global~.
3465 You might want to bind them to globally available keys. See
3466 [[*Activation]] for some advice.
3468 ** Link Abbreviations
3470 :DESCRIPTION: Shortcuts for writing complex links.
3472 #+cindex: link abbreviations
3473 #+cindex: abbreviation, links
3475 Long URL can be cumbersome to type, and often many similar links are
3476 needed in a document. For this you can use link abbreviations. An
3477 abbreviated link looks like this
3479 : [[linkword:tag][description]]
3481 #+texinfo: @noindent
3482 #+vindex: org-link-abbrev-alist
3483 where the tag is optional. The /linkword/ must be a word, starting
3484 with a letter, followed by letters, numbers, =-=, and =_=.
3485 Abbreviations are resolved according to the information in the
3486 variable ~org-link-abbrev-alist~ that relates the linkwords to
3487 replacement text. Here is an example:
3489 #+begin_src emacs-lisp
3490 (setq org-link-abbrev-alist
3491 '(("bugzilla" . "http://10.1.2.9/bugzilla/show_bug.cgi?id=")
3492 ("url-to-ja" . "http://translate.google.fr/translate?sl=en&tl=ja&u=%h")
3493 ("google" . "http://www.google.com/search?q=")
3494 ("gmap" . "http://maps.google.com/maps?q=%s")
3495 ("omap" . "http://nominatim.openstreetmap.org/search?q=%s&polygon=1")
3496 ("ads" . "http://adsabs.harvard.edu/cgi-bin/nph-abs_connect?author=%s&db_key=AST")))
3499 If the replacement text contains the string =%s=, it is replaced with
3500 the tag. Using =%h= instead of =%s= percent-encodes the tag (see the
3501 example above, where we need to encode the URL parameter). Using
3502 =%(my-function)= passes the tag to a custom Lisp function, and replace
3503 it by the resulting string.
3505 If the replacement text do not contain any specifier, it is simply
3506 appended to the string in order to create the link.
3508 Instead of a string, you may also specify a Lisp function to create
3509 the link. Such a function will be called with the tag as the only
3512 With the above setting, you could link to a specific bug with
3513 =[[bugzilla:129]]=, search the web for =OrgMode= with =[[google:OrgMode]]=,
3514 show the map location of the Free Software Foundation =[[gmap:51
3515 Franklin Street, Boston]]= or of Carsten office =[[omap:Science Park 904,
3516 Amsterdam, The Netherlands]]= and find out what the Org author is doing
3517 besides Emacs hacking with =[[ads:Dominik,C]]=.
3519 If you need special abbreviations just for a single Org buffer, you
3520 can define them in the file with
3522 #+cindex: @samp{LINK}, keyword
3524 ,#+LINK: bugzilla http://10.1.2.9/bugzilla/show_bug.cgi?id=
3525 ,#+LINK: google http://www.google.com/search?q=%s
3528 In-buffer completion (see [[*Completion]]) can be used after =[= to
3529 complete link abbreviations. You may also define a Lisp function that
3530 implements special (e.g., completion) support for inserting such a
3531 link with {{{kbd(C-c C-l)}}}. Such a function should not accept any
3532 arguments, and should return the full link with a prefix. You can set
3533 the link completion function like this:
3535 #+begin_src emacs-lisp
3536 (org-link-set-parameter "type" :complete #'some-completion-function)
3539 ** Search Options in File Links
3541 :DESCRIPTION: Linking to a specific location.
3542 :ALT_TITLE: Search Options
3544 #+cindex: search option in file links
3545 #+cindex: file links, searching
3547 File links can contain additional information to make Emacs jump to
3548 a particular location in the file when following a link. This can be
3549 a line number or a search option after a double colon[fn:36]. For
3550 example, when the command ~org-store-link~ creates a link (see
3551 [[*Handling Links]]) to a file, it encodes the words in the current line
3552 as a search string that can be used to find this line back later when
3553 following the link with {{{kbd(C-c C-o)}}}.
3555 Here is the syntax of the different ways to attach a search to a file
3556 link, together with explanations for each:
3559 [[file:~/code/main.c::255]]
3560 [[file:~/xx.org::My Target]]
3561 [[file:~/xx.org::*My Target]]
3562 [[file:~/xx.org::#my-custom-id]]
3563 [[file:~/xx.org::/regexp/]]
3572 Search for a link target =<<My Target>>=, or do a text search for
3573 =my target=, similar to the search in internal links, see [[*Internal
3574 Links]]. In HTML export (see [[*HTML Export]]), such a file link becomes
3575 a HTML reference to the corresponding named anchor in the linked
3580 In an Org file, restrict search to headlines.
3582 - =#my-custom-id= ::
3584 Link to a heading with a =CUSTOM_ID= property
3588 Do a regular expression search for {{{var(REGEXP)}}}. This uses the
3589 Emacs command ~occur~ to list all matches in a separate window. If
3590 the target file is in Org mode, ~org-occur~ is used to create
3591 a sparse tree with the matches.
3593 As a degenerate case, a file link with an empty file name can be used
3594 to search the current file. For example, =[[file:::find me]]= does
3595 a search for =find me= in the current file, just as =[[find me]]=
3600 :DESCRIPTION: When the default search is not enough.
3602 #+cindex: custom search strings
3603 #+cindex: search strings, custom
3605 The default mechanism for creating search strings and for doing the
3606 actual search related to a file link may not work correctly in all
3607 cases. For example, BibTeX database files have many entries like
3608 ~year="1993"~ which would not result in good search strings, because
3609 the only unique identification for a BibTeX entry is the citation key.
3611 #+vindex: org-create-file-search-functions
3612 #+vindex: org-execute-file-search-functions
3613 If you come across such a problem, you can write custom functions to
3614 set the right search string for a particular file type, and to do the
3615 search for the string in the file. Using ~add-hook~, these functions
3616 need to be added to the hook variables
3617 ~org-create-file-search-functions~ and
3618 ~org-execute-file-search-functions~. See the docstring for these
3619 variables for more information. Org actually uses this mechanism for
3620 BibTeX database files, and you can use the corresponding code as an
3621 implementation example. See the file =org-bibtex.el=.
3625 :DESCRIPTION: Every tree branch can be a TODO item.
3627 #+cindex: TODO items
3629 Org mode does not maintain TODO lists as separate documents[fn:37].
3630 Instead, TODO items are an integral part of the notes file, because
3631 TODO items usually come up while taking notes! With Org mode, simply
3632 mark any entry in a tree as being a TODO item. In this way,
3633 information is not duplicated, and the entire context from which the
3634 TODO item emerged is always present.
3636 Of course, this technique for managing TODO items scatters them
3637 throughout your notes file. Org mode compensates for this by
3638 providing methods to give you an overview of all the things that you
3641 ** Basic TODO Functionality
3643 :DESCRIPTION: Marking and displaying TODO entries.
3644 :ALT_TITLE: TODO Basics
3647 Any headline becomes a TODO item when it starts with the word =TODO=,
3650 : *** TODO Write letter to Sam Fortune
3652 The most important commands to work with TODO entries are:
3654 - {{{kbd(C-c C-t)}}} (~org-todo~) ::
3657 #+cindex: cycling, of TODO states
3658 Rotate the TODO state of the current item among
3661 ,-> (unmarked) -> TODO -> DONE --.
3662 '--------------------------------'
3665 If TODO keywords have fast access keys (see [[*Fast access to TODO
3666 states]]), prompt for a TODO keyword through the fast selection
3667 interface; this is the default behavior when
3668 ~org-use-fast-todo-selection~ is non-~nil~.
3670 The same rotation can also be done "remotely" from the agenda buffer
3671 with the {{{kbd(t)}}} command key (see [[*Commands in the Agenda
3674 - {{{kbd(C-u C-c C-t)}}} ::
3676 #+kindex: C-u C-c C-t
3677 When TODO keywords have no selection keys, select a specific keyword
3678 using completion; otherwise force cycling through TODO states with
3679 no prompt. When ~org-use-fast-todo-selection~ is set to ~prefix~,
3680 use the fast selection interface.
3682 - {{{kbd(S-RIGHT)}}} {{{kbd(S-LEFT)}}} ::
3686 #+vindex: org-treat-S-cursor-todo-selection-as-state-change
3687 Select the following/preceding TODO state, similar to cycling.
3688 Useful mostly if more than two TODO states are possible (see
3689 [[*Extended Use of TODO Keywords]]). See also [[*Packages that conflict
3690 with Org mode]], for a discussion of the interaction with
3691 ~shift-selection-mode~. See also the variable
3692 ~org-treat-S-cursor-todo-selection-as-state-change~.
3694 - {{{kbd(C-c / t)}}} (~org-show-todo-tree~) ::
3697 #+cindex: sparse tree, for TODO
3698 #+vindex: org-todo-keywords
3699 #+findex: org-show-todo-tree
3700 View TODO items in a /sparse tree/ (see [[*Sparse Trees]]). Folds the
3701 entire buffer, but shows all TODO items---with not-DONE state---and
3702 the headings hierarchy above them. With a prefix argument, or by
3703 using {{{kbd(C-c / T)}}}, search for a specific TODO. You are
3704 prompted for the keyword, and you can also give a list of keywords
3705 like =KWD1|KWD2|...= to list entries that match any one of these
3706 keywords. With a numeric prefix argument N, show the tree for the
3707 Nth keyword in the variable ~org-todo-keywords~. With two prefix
3708 arguments, find all TODO states, both un-done and done.
3710 - {{{kbd(M-x org-agenda t)}}} (~org-todo-list~) ::
3712 #+kindex: t @r{(Agenda dispatcher)}
3713 Show the global TODO list. Collects the TODO items (with not-DONE
3714 states) from all agenda files (see [[*Agenda Views]]) into a single
3715 buffer. The new buffer is in Org Agenda mode, which provides
3716 commands to examine and manipulate the TODO entries from the new
3717 buffer (see [[*Commands in the Agenda Buffer]]). See [[*The global TODO
3718 list]], for more information.
3720 - {{{kbd(S-M-RET)}}} (~org-insert-todo-heading~) ::
3723 #+findex: org-insert-todo-heading
3724 Insert a new TODO entry below the current one.
3726 #+vindex: org-todo-state-tags-triggers
3727 Changing a TODO state can also trigger tag changes. See the docstring
3728 of the option ~org-todo-state-tags-triggers~ for details.
3730 ** Extended Use of TODO Keywords
3732 :DESCRIPTION: Workflow and assignments.
3733 :ALT_TITLE: TODO Extensions
3735 #+cindex: extended TODO keywords
3737 #+vindex: org-todo-keywords
3738 By default, marked TODO entries have one of only two states: TODO and
3739 DONE. Org mode allows you to classify TODO items in more complex ways
3740 with /TODO keywords/ (stored in ~org-todo-keywords~). With special
3741 setup, the TODO keyword system can work differently in different
3744 Note that /tags/ are another way to classify headlines in general and
3745 TODO items in particular (see [[*Tags]]).
3747 *** TODO keywords as workflow states
3749 :DESCRIPTION: From TODO to DONE in steps.
3750 :ALT_TITLE: Workflow states
3752 #+cindex: TODO workflow
3753 #+cindex: workflow states as TODO keywords
3755 You can use TODO keywords to indicate different /sequential/ states in
3756 the process of working on an item, for example[fn:38]:
3758 #+begin_src emacs-lisp
3759 (setq org-todo-keywords
3760 '((sequence "TODO" "FEEDBACK" "VERIFY" "|" "DONE" "DELEGATED")))
3763 The vertical bar separates the TODO keywords (states that /need
3764 action/) from the DONE states (which need /no further action/). If
3765 you do not provide the separator bar, the last state is used as the
3768 #+cindex: completion, of TODO keywords
3769 With this setup, the command {{{kbd(C-c C-t)}}} cycles an entry from
3770 =TODO= to =FEEDBACK=, then to =VERIFY=, and finally to =DONE= and
3771 =DELEGATED=. You may also use a numeric prefix argument to quickly
3772 select a specific state. For example {{{kbd(C-3 C-c C-t)}}} changes
3773 the state immediately to =VERIFY=. Or you can use {{{kbd(S-LEFT)}}}
3774 to go backward through the sequence. If you define many keywords, you
3775 can use in-buffer completion (see [[*Completion]]) or even a special
3776 one-key selection scheme (see [[*Fast access to TODO states]]) to insert
3777 these words into the buffer. Changing a TODO state can be logged with
3778 a timestamp, see [[*Tracking TODO state changes]], for more information.
3780 *** TODO keywords as types
3782 :DESCRIPTION: I do this, Fred does the rest.
3783 :ALT_TITLE: TODO types
3785 #+cindex: TODO types
3786 #+cindex: names as TODO keywords
3787 #+cindex: types as TODO keywords
3789 The second possibility is to use TODO keywords to indicate different
3790 /types/ of action items. For example, you might want to indicate that
3791 items are for "work" or "home". Or, when you work with several people
3792 on a single project, you might want to assign action items directly to
3793 persons, by using their names as TODO keywords. This would be set up
3796 #+begin_src emacs-lisp
3797 (setq org-todo-keywords '((type "Fred" "Sara" "Lucy" "|" "DONE")))
3800 In this case, different keywords do not indicate a sequence, but
3801 rather different types. So the normal work flow would be to assign
3802 a task to a person, and later to mark it DONE. Org mode supports this
3803 style by adapting the workings of the command {{{kbd(C-c
3804 C-t)}}}[fn:39]. When used several times in succession, it still
3805 cycles through all names, in order to first select the right type for
3806 a task. But when you return to the item after some time and execute
3807 {{{kbd(C-c C-t)}}} again, it will switch from any name directly to
3808 =DONE=. Use prefix arguments or completion to quickly select
3809 a specific name. You can also review the items of a specific TODO
3810 type in a sparse tree by using a numeric prefix to {{{kbd(C-c / t)}}}.
3811 For example, to see all things Lucy has to do, you would use
3812 {{{kbd(C-3 C-c / t)}}}. To collect Lucy's items from all agenda files
3813 into a single buffer, you would use the numeric prefix argument as
3814 well when creating the global TODO list: {{{kbd(C-3 M-x org-agenda
3817 *** Multiple keyword sets in one file
3819 :DESCRIPTION: Mixing it all, still finding your way.
3820 :ALT_TITLE: Multiple sets in one file
3822 #+cindex: TODO keyword sets
3824 Sometimes you may want to use different sets of TODO keywords in
3825 parallel. For example, you may want to have the basic TODO/DONE, but
3826 also a workflow for bug fixing, and a separate state indicating that
3827 an item has been canceled---so it is not DONE, but also does not
3828 require action. Your setup would then look like this:
3830 #+begin_src emacs-lisp
3831 (setq org-todo-keywords
3832 '((sequence "TODO" "|" "DONE")
3833 (sequence "REPORT" "BUG" "KNOWNCAUSE" "|" "FIXED")
3834 (sequence "|" "CANCELED")))
3837 The keywords should all be different, this helps Org mode keep track
3838 of which subsequence should be used for a given entry. In this setup,
3839 {{{kbd(C-c C-t)}}} only operates within a sub-sequence, so it switches
3840 from =DONE= to (nothing) to =TODO=, and from =FIXED= to (nothing) to
3841 =REPORT=. Therefore you need a mechanism to initially select the
3842 correct sequence. In addition to typing a keyword or using completion
3843 (see [[*Completion]]), you may also apply the following commands:
3845 #+attr_texinfo: :sep ,
3846 - {{{kbd(C-u C-u C-c C-t)}}}, {{{kbd(C-S-RIGHT)}}}, {{{kbd(C-S-LEFT)}}} ::
3850 #+kindex: C-u C-u C-c C-t
3851 These keys jump from one TODO sub-sequence to the next. In the
3852 above example, {{{kbd(C-u C-u C-c C-t)}}} or {{{kbd(C-S-RIGHT)}}}
3853 would jump from =TODO= or =DONE= to =REPORT=, and any of the words
3854 in the second row to =CANCELED=. Note that the {{{kbd(C-S-)}}} key
3855 binding conflict with ~shift-selection-mode~ (see [[*Packages that
3856 conflict with Org mode]]).
3858 - {{{kbd(S-RIGHT)}}}, {{{kbd(S-LEFT)}}} ::
3862 {{{kbd(S-LEFT)}}} and {{{kbd(S-RIGHT)}}} walk through /all/ keywords
3863 from all sub-sequences, so for example {{{kbd(S-RIGHT)}}} would
3864 switch from =DONE= to =REPORT= in the example above. For
3865 a discussion of the interaction with ~shift-selection-mode~, see
3866 [[*Packages that conflict with Org mode]].
3868 *** Fast access to TODO states
3870 :DESCRIPTION: Single letter selection of state.
3873 If you would like to quickly change an entry to an arbitrary TODO
3874 state instead of cycling through the states, you can set up keys for
3875 single-letter access to the states. This is done by adding the
3876 selection character after each keyword, in parentheses[fn:40]. For
3879 #+begin_src emacs-lisp
3880 (setq org-todo-keywords
3881 '((sequence "TODO(t)" "|" "DONE(d)")
3882 (sequence "REPORT(r)" "BUG(b)" "KNOWNCAUSE(k)" "|" "FIXED(f)")
3883 (sequence "|" "CANCELED(c)")))
3886 #+vindex: org-fast-tag-selection-include-todo
3887 If you then press {{{kbd(C-c C-t)}}} followed by the selection key,
3888 the entry is switched to this state. {{{kbd(SPC)}}} can be used to
3889 remove any TODO keyword from an entry[fn:41].
3891 *** Setting up keywords for individual files
3893 :DESCRIPTION: Different files, different requirements.
3894 :ALT_TITLE: Per-file keywords
3896 #+cindex: keyword options
3897 #+cindex: per-file keywords
3898 #+cindex: @samp{TODO}, keyword
3899 #+cindex: @samp{TYP_TODO}, keyword
3900 #+cindex: @samp{SEQ_TODO}, keyword
3902 It can be very useful to use different aspects of the TODO mechanism
3903 in different files. For file-local settings, you need to add special
3904 lines to the file which set the keywords and interpretation for that
3905 file only. For example, to set one of the two examples discussed
3906 above, you need one of the following lines, starting in column zero
3907 anywhere in the file:
3909 : #+TODO: TODO FEEDBACK VERIFY | DONE CANCELED
3911 You may also write =#+SEQ_TODO= to be explicit about the
3912 interpretation, but it means the same as =#+TODO=, or
3914 : #+TYP_TODO: Fred Sara Lucy Mike | DONE
3916 A setup for using several sets in parallel would be:
3919 ,#+TODO: TODO | DONE
3920 ,#+TODO: REPORT BUG KNOWNCAUSE | FIXED
3924 #+cindex: completion, of option keywords
3926 To make sure you are using the correct keyword, type =#+= into the
3927 buffer and then use {{{kbd(M-TAB)}}} to complete it (see [[*Completion]]).
3929 #+cindex: DONE, final TODO keyword
3930 Remember that the keywords after the vertical bar---or the last
3931 keyword if no bar is there---must always mean that the item is DONE,
3932 although you may use a different word. After changing one of these
3933 lines, use {{{kbd(C-c C-c)}}} with point still in the line to make the
3934 changes known to Org mode[fn:42].
3936 *** Faces for TODO keywords
3938 :DESCRIPTION: Highlighting states.
3940 #+cindex: faces, for TODO keywords
3942 #+vindex: org-todo, face
3943 #+vindex: org-done, face
3944 #+vindex: org-todo-keyword-faces
3945 Org mode highlights TODO keywords with special faces: ~org-todo~ for
3946 keywords indicating that an item still has to be acted upon, and
3947 ~org-done~ for keywords indicating that an item is finished. If you
3948 are using more than two different states, you might want to use
3949 special faces for some of them. This can be done using the variable
3950 ~org-todo-keyword-faces~. For example:
3952 #+begin_src emacs-lisp
3953 (setq org-todo-keyword-faces
3954 '(("TODO" . org-warning) ("STARTED" . "yellow")
3955 ("CANCELED" . (:foreground "blue" :weight bold))))
3958 #+vindex: org-faces-easy-properties
3959 While using a list with face properties as shown for =CANCELED=
3960 /should/ work, this does not always seem to be the case. If
3961 necessary, define a special face and use that. A string is
3962 interpreted as a color. The variable ~org-faces-easy-properties~
3963 determines if that color is interpreted as a foreground or
3966 *** TODO dependencies
3968 :DESCRIPTION: When one task needs to wait for others.
3970 #+cindex: TODO dependencies
3971 #+cindex: dependencies, of TODO states
3973 #+vindex: org-enforce-todo-dependencies
3974 #+cindex: @samp{ORDERED}, property
3975 The structure of Org files---hierarchy and lists---makes it easy to
3976 define TODO dependencies. Usually, a parent TODO task should not be
3977 marked DONE until all TODO subtasks, or children tasks, are marked as
3978 DONE. Sometimes there is a logical sequence to (sub)tasks, so that
3979 one subtask cannot be acted upon before all siblings above it have
3980 been marked DONE. If you customize the variable
3981 ~org-enforce-todo-dependencies~, Org blocks entries from changing
3982 state to DONE while they have TODO children that are not DONE.
3983 Furthermore, if an entry has a property =ORDERED=, each of its TODO
3984 children is blocked until all earlier siblings are marked DONE. Here
3988 ,* TODO Blocked until (two) is done
3997 ,** TODO b, needs to wait for (a)
3998 ,** TODO c, needs to wait for (a) and (b)
4001 #+cindex: TODO dependencies, @samp{NOBLOCKING}
4002 #+cindex: @samp{NOBLOCKING}, property
4003 You can ensure an entry is never blocked by using the =NOBLOCKING=
4004 property (see [[*Properties and Columns]]):
4007 ,* This entry is never blocked
4013 - {{{kbd(C-c C-x o)}}} (~org-toggle-ordered-property~) ::
4016 #+findex: org-toggle-ordered-property
4017 #+vindex: org-track-ordered-property-with-tag
4018 Toggle the =ORDERED= property of the current entry. A property is
4019 used for this behavior because this should be local to the current
4020 entry, not inherited from entries above like a tag (see [[*Tags]]).
4021 However, if you would like to /track/ the value of this property
4022 with a tag for better visibility, customize the variable
4023 ~org-track-ordered-property-with-tag~.
4025 - {{{kbd(C-u C-u C-u C-c C-t)}}} ::
4027 #+kindex: C-u C-u C-u C-c C-t
4028 Change TODO state, regardless of any state blocking.
4030 #+vindex: org-agenda-dim-blocked-tasks
4031 If you set the variable ~org-agenda-dim-blocked-tasks~, TODO entries
4032 that cannot be marked DONE because of unmarked children are shown in a
4033 dimmed font or even made invisible in agenda views (see [[*Agenda
4036 #+cindex: checkboxes and TODO dependencies
4037 #+vindex: org-enforce-todo-dependencies
4038 You can also block changes of TODO states by using checkboxes (see
4039 [[*Checkboxes]]). If you set the variable
4040 ~org-enforce-todo-checkbox-dependencies~, an entry that has unchecked
4041 checkboxes is blocked from switching to DONE.
4043 If you need more complex dependency structures, for example
4044 dependencies between entries in different trees or files, check out
4045 the contributed module =org-depend.el=.
4049 :DESCRIPTION: Dates and notes for progress.
4051 #+cindex: progress logging
4052 #+cindex: logging, of progress
4054 Org mode can automatically record a timestamp and optionally a note
4055 when you mark a TODO item as DONE, or even each time you change the
4056 state of a TODO item. This system is highly configurable, settings
4057 can be on a per-keyword basis and can be localized to a file or even a
4058 subtree. For information on how to clock working time for a task, see
4059 [[*Clocking Work Time]].
4063 :DESCRIPTION: When was this entry marked DONE?
4066 The most basic logging is to keep track of /when/ a certain TODO item
4067 was marked DONE. This can be achieved with[fn:43]
4069 #+begin_src emacs-lisp
4070 (setq org-log-done 'time)
4073 #+vindex: org-closed-keep-when-no-todo
4074 #+texinfo: @noindent
4075 Then each time you turn an entry from a TODO (not-done) state into any
4076 of the DONE states, a line =CLOSED: [timestamp]= is inserted just
4077 after the headline. If you turn the entry back into a TODO item
4078 through further state cycling, that line is removed again. If you
4079 turn the entry back to a non-TODO state (by pressing {{{kbd(C-c C-t
4080 SPC)}}} for example), that line is also removed, unless you set
4081 ~org-closed-keep-when-no-todo~ to non-~nil~. If you want to record
4082 a note along with the timestamp, use[fn:44]
4084 #+begin_src emacs-lisp
4085 (setq org-log-done 'note)
4088 #+texinfo: @noindent
4089 You are then be prompted for a note, and that note is stored below the
4090 entry with a =Closing Note= heading.
4092 *** Tracking TODO state changes
4094 :DESCRIPTION: When did the status change?
4096 #+cindex: drawer, for state change recording
4098 #+vindex: org-log-states-order-reversed
4099 #+vindex: org-log-into-drawer
4100 #+cindex: @samp{LOG_INTO_DRAWER}, property
4101 When TODO keywords are used as workflow states (see [[*TODO keywords as workflow states][*Workflow states]]),
4102 you might want to keep track of when a state change occurred and maybe
4103 take a note about this change. You can either record just a
4104 timestamp, or a time-stamped note. These records are inserted after
4105 the headline as an itemized list, newest first[fn:45]. When taking a
4106 lot of notes, you might want to get the notes out of the way into a
4107 drawer (see [[*Drawers]]). Customize the variable ~org-log-into-drawer~
4108 to get this behavior---the recommended drawer for this is called
4109 =LOGBOOK=[fn:46]. You can also overrule the setting of this variable
4110 for a subtree by setting a =LOG_INTO_DRAWER= property.
4112 Since it is normally too much to record a note for every state, Org
4113 mode expects configuration on a per-keyword basis for this. This is
4114 achieved by adding special markers =!= (for a timestamp) or =@= (for
4115 a note with timestamp) in parentheses after each keyword. For
4116 example, with the setting
4118 #+begin_src emacs-lisp
4119 (setq org-todo-keywords
4120 '((sequence "TODO(t)" "WAIT(w@/!)" "|" "DONE(d!)" "CANCELED(c@)")))
4123 #+texinfo: @noindent
4124 to record a timestamp without a note for TODO keywords configured with
4125 =@=, just type {{{kbd(C-c C-c)}}} to enter a blank note when prompted.
4127 #+vindex: org-log-done
4128 You not only define global TODO keywords and fast access keys, but
4129 also request that a time is recorded when the entry is set to =DONE=,
4130 and that a note is recorded when switching to =WAIT= or
4131 =CANCELED=[fn:47]. The setting for =WAIT= is even more special: the
4132 =!= after the slash means that in addition to the note taken when
4133 entering the state, a timestamp should be recorded when /leaving/ the
4134 =WAIT= state, if and only if the /target/ state does not configure
4135 logging for entering it. So it has no effect when switching from
4136 =WAIT= to =DONE=, because =DONE= is configured to record a timestamp
4137 only. But when switching from =WAIT= back to =TODO=, the =/!= in the
4138 =WAIT= setting now triggers a timestamp even though =TODO= has no
4141 You can use the exact same syntax for setting logging preferences local
4144 : #+TODO: TODO(t) WAIT(w@/!) | DONE(d!) CANCELED(c@)
4146 #+cindex: @samp{LOGGING}, property
4147 In order to define logging settings that are local to a subtree or
4148 a single item, define a =LOGGING= property in this entry. Any
4149 non-empty =LOGGING= property resets all logging settings to ~nil~.
4150 You may then turn on logging for this specific tree using =STARTUP=
4151 keywords like =lognotedone= or =logrepeat=, as well as adding state
4152 specific settings like =TODO(!)=. For example:
4155 ,* TODO Log each state with only a time
4157 :LOGGING: TODO(!) WAIT(!) DONE(!) CANCELED(!)
4159 ,* TODO Only log when switching to WAIT, and when repeating
4161 :LOGGING: WAIT(@) logrepeat
4163 ,* TODO No logging at all
4169 *** Tracking your habits
4171 :DESCRIPTION: How consistent have you been?
4174 #+cindex: @samp{STYLE}, property
4176 Org has the ability to track the consistency of a special category of
4177 TODO, called "habits." To use habits, you have to enable the ~habits~
4178 module by customizing the variable ~org-modules~.
4180 A habit has the following properties:
4182 1. The habit is a TODO item, with a TODO keyword representing an open
4185 2. The property =STYLE= is set to the value =habit= (see [[*Properties
4188 3. The TODO has a scheduled date, usually with a =.+= style repeat
4189 interval. A =++= style may be appropriate for habits with time
4190 constraints, e.g., must be done on weekends, or a =+= style for an
4191 unusual habit that can have a backlog, e.g., weekly reports.
4193 4. The TODO may also have minimum and maximum ranges specified by
4194 using the syntax =.+2d/3d=, which says that you want to do the task
4195 at least every three days, but at most every two days.
4197 5. State logging for the DONE state is enabled (see [[*Tracking TODO
4198 state changes]]), in order for historical data to be represented in
4199 the consistency graph. If it is not enabled it is not an error,
4200 but the consistency graphs are largely meaningless.
4202 To give you an idea of what the above rules look like in action, here's an
4203 actual habit with some history:
4207 SCHEDULED: <2009-10-17 Sat .+2d/4d>
4210 :LAST_REPEAT: [2009-10-19 Mon 00:36]
4212 - State "DONE" from "TODO" [2009-10-15 Thu]
4213 - State "DONE" from "TODO" [2009-10-12 Mon]
4214 - State "DONE" from "TODO" [2009-10-10 Sat]
4215 - State "DONE" from "TODO" [2009-10-04 Sun]
4216 - State "DONE" from "TODO" [2009-10-02 Fri]
4217 - State "DONE" from "TODO" [2009-09-29 Tue]
4218 - State "DONE" from "TODO" [2009-09-25 Fri]
4219 - State "DONE" from "TODO" [2009-09-19 Sat]
4220 - State "DONE" from "TODO" [2009-09-16 Wed]
4221 - State "DONE" from "TODO" [2009-09-12 Sat]
4224 What this habit says is: I want to shave at most every 2 days---given
4225 by the =SCHEDULED= date and repeat interval---and at least every
4226 4 days. If today is the 15th, then the habit first appears in the
4227 agenda (see [[*Agenda Views]]) on Oct 17, after the minimum of 2 days has
4228 elapsed, and will appear overdue on Oct 19, after four days have
4231 What's really useful about habits is that they are displayed along
4232 with a consistency graph, to show how consistent you've been at
4233 getting that task done in the past. This graph shows every day that
4234 the task was done over the past three weeks, with colors for each day.
4235 The colors used are:
4237 - Blue :: If the task was not to be done yet on that day.
4238 - Green :: If the task could have been done on that day.
4239 - Yellow :: If the task was going to be overdue the next day.
4240 - Red :: If the task was overdue on that day.
4242 In addition to coloring each day, the day is also marked with an
4243 asterisk if the task was actually done that day, and an exclamation
4244 mark to show where the current day falls in the graph.
4246 There are several configuration variables that can be used to change
4247 the way habits are displayed in the agenda.
4249 - ~org-habit-graph-column~ ::
4251 #+vindex: org-habit-graph-column
4252 The buffer column at which the consistency graph should be drawn.
4253 This overwrites any text in that column, so it is a good idea to
4254 keep your habits' titles brief and to the point.
4256 - ~org-habit-preceding-days~ ::
4258 #+vindex: org-habit-preceding-days
4259 The amount of history, in days before today, to appear in
4262 - ~org-habit-following-days~ ::
4264 #+vindex: org-habit-following-days
4265 The number of days after today that appear in consistency graphs.
4267 - ~org-habit-show-habits-only-for-today~ ::
4269 #+vindex: org-habit-show-habits-only-for-today
4270 If non-~nil~, only show habits in today's agenda view. The default
4273 Lastly, pressing {{{kbd(K)}}} in the agenda buffer causes habits to
4274 temporarily be disabled and do not appear at all. Press {{{kbd(K)}}}
4275 again to bring them back. They are also subject to tag filtering, if
4276 you have habits which should only be done in certain contexts, for
4281 :DESCRIPTION: Some things are more important than others.
4283 #+cindex: priorities
4284 #+cindex: priority cookie
4286 If you use Org mode extensively, you may end up with enough TODO items
4287 that it starts to make sense to prioritize them. Prioritizing can be
4288 done by placing a /priority cookie/ into the headline of a TODO item,
4291 : *** TODO [#A] Write letter to Sam Fortune
4293 #+vindex: org-priority-faces
4294 By default, Org mode supports three priorities: =A=, =B=, and =C=.
4295 =A= is the highest priority. An entry without a cookie is treated as
4296 equivalent if it had priority =B=. Priorities make a difference only
4297 for sorting in the agenda (see [[*Weekly/daily agenda]]); outside the
4298 agenda, they have no inherent meaning to Org mode. The cookies are
4299 displayed with the face defined by the variable ~org-priority-faces~,
4300 which can be customized.
4302 Priorities can be attached to any outline node; they do not need to be
4305 #+attr_texinfo: :sep ;
4306 - {{{kbd(C-c \,)}}} (~org-priority~) ::
4309 #+findex: org-priority
4310 Set the priority of the current headline. The command prompts for
4311 a priority character =A=, =B= or =C=. When you press {{{kbd(SPC)}}}
4312 instead, the priority cookie, if one is set, is removed from the
4313 headline. The priorities can also be changed "remotely" from the
4314 agenda buffer with the {{{kbd(\,)}}} command (see [[*Commands in the
4317 - {{{kbd(S-UP)}}} (~org-priority-up~); {{{kbd(S-DOWN)}}} (~org-priority-down~) ::
4321 #+findex: org-priority-up
4322 #+findex: org-priority-down
4323 #+vindex: org-priority-start-cycle-with-default
4324 Increase/decrease the priority of the current headline[fn:48]. Note
4325 that these keys are also used to modify timestamps (see [[*Creating
4326 Timestamps]]). See also [[*Packages that conflict with Org mode]], for
4327 a discussion of the interaction with ~shift-selection-mode~.
4329 #+vindex: org-highest-priority
4330 #+vindex: org-lowest-priority
4331 #+vindex: org-default-priority
4332 You can change the range of allowed priorities by setting the
4333 variables ~org-highest-priority~, ~org-lowest-priority~, and
4334 ~org-default-priority~. For an individual buffer, you may set these
4335 values (highest, lowest, default) like this (please make sure that the
4336 highest priority is earlier in the alphabet than the lowest priority):
4338 #+cindex: @samp{PRIORITIES}, keyword
4339 : #+PRIORITIES: A C B
4341 ** Breaking Down Tasks into Subtasks
4343 :DESCRIPTION: Splitting a task into manageable pieces.
4344 :ALT_TITLE: Breaking Down Tasks
4346 #+cindex: tasks, breaking down
4347 #+cindex: statistics, for TODO items
4349 #+vindex: org-agenda-todo-list-sublevels
4350 It is often advisable to break down large tasks into smaller,
4351 manageable subtasks. You can do this by creating an outline tree
4352 below a TODO item, with detailed subtasks on the tree[fn:49]. To keep
4353 an overview of the fraction of subtasks that have already been marked
4354 DONE, insert either =[/]= or =[%]= anywhere in the headline. These
4355 cookies are updated each time the TODO status of a child changes, or
4356 when pressing {{{kbd(C-c C-c)}}} on the cookie. For example:
4359 ,* Organize Party [33%]
4360 ,** TODO Call people [1/2]
4364 ,** DONE Talk to neighbor
4367 #+cindex: @samp{COOKIE_DATA}, property
4368 If a heading has both checkboxes and TODO children below it, the
4369 meaning of the statistics cookie become ambiguous. Set the property
4370 =COOKIE_DATA= to either =checkbox= or =todo= to resolve this issue.
4372 #+vindex: org-hierarchical-todo-statistics
4373 If you would like to have the statistics cookie count any TODO entries
4374 in the subtree (not just direct children), configure the variable
4375 ~org-hierarchical-todo-statistics~. To do this for a single subtree,
4376 include the word =recursive= into the value of the =COOKIE_DATA=
4380 ,* Parent capturing statistics [2/20]
4382 :COOKIE_DATA: todo recursive
4386 If you would like a TODO entry to automatically change to DONE when
4387 all children are done, you can use the following setup:
4389 #+begin_src emacs-lisp
4390 (defun org-summary-todo (n-done n-not-done)
4391 "Switch entry to DONE when all subentries are done, to TODO otherwise."
4392 (let (org-log-done org-log-states) ; turn off logging
4393 (org-todo (if (= n-not-done 0) "DONE" "TODO"))))
4395 (add-hook 'org-after-todo-statistics-hook 'org-summary-todo)
4398 Another possibility is the use of checkboxes to identify (a hierarchy
4399 of) a large number of subtasks (see [[*Checkboxes]]).
4403 :DESCRIPTION: Tick-off lists.
4405 #+cindex: checkboxes
4407 #+vindex: org-list-automatic-rules
4408 Every item in a plain list[fn:50] (see [[*Plain Lists]]) can be made into
4409 a checkbox by starting it with the string =[ ]=. This feature is
4410 similar to TODO items (see [[*TODO Items]]), but is more lightweight.
4411 Checkboxes are not included into the global TODO list, so they are
4412 often great to split a task into a number of simple steps. Or you can
4413 use them in a shopping list. To toggle a checkbox, use {{{kbd(C-c
4414 C-c)}}}, or use the mouse (thanks to Piotr Zielinski's
4417 Here is an example of a checkbox list.
4420 ,* TODO Organize party [2/4]
4421 - [-] call people [1/3]
4426 - [ ] think about what music to play
4427 - [X] talk to the neighbors
4430 Checkboxes work hierarchically, so if a checkbox item has children
4431 that are checkboxes, toggling one of the children checkboxes makes the
4432 parent checkbox reflect if none, some, or all of the children are
4435 #+cindex: statistics, for checkboxes
4436 #+cindex: checkbox statistics
4437 #+cindex: @samp{COOKIE_DATA}, property
4438 #+vindex: org-hierarchical-checkbox-statistics
4439 The =[2/4]= and =[1/3]= in the first and second line are cookies
4440 indicating how many checkboxes present in this entry have been checked
4441 off, and the total number of checkboxes present. This can give you an
4442 idea on how many checkboxes remain, even without opening a folded
4443 entry. The cookies can be placed into a headline or into (the first
4444 line of) a plain list item. Each cookie covers checkboxes of direct
4445 children structurally below the headline/item on which the cookie
4446 appears[fn:51]. You have to insert the cookie yourself by typing
4447 either =[/]= or =[%]=. With =[/]= you get an =n out of m= result, as
4448 in the examples above. With =[%]= you get information about the
4449 percentage of checkboxes checked (in the above example, this would be
4450 =[50%]= and =[33%]=, respectively). In a headline, a cookie can count
4451 either checkboxes below the heading or TODO states of children, and it
4452 displays whatever was changed last. Set the property =COOKIE_DATA= to
4453 either =checkbox= or =todo= to resolve this issue.
4455 #+cindex: blocking, of checkboxes
4456 #+cindex: checkbox blocking
4457 #+cindex: @samp{ORDERED}, property
4458 If the current outline node has an =ORDERED= property, checkboxes must
4459 be checked off in sequence, and an error is thrown if you try to check
4460 off a box while there are unchecked boxes above it.
4462 The following commands work with checkboxes:
4464 - {{{kbd(C-c C-c)}}} (~org-toggle-checkbox~) ::
4467 #+findex: org-toggle-checkbox
4468 Toggle checkbox status or---with prefix argument---checkbox presence
4469 at point. With a single prefix argument, add an empty checkbox or
4470 remove the current one[fn:52]. With a double prefix argument, set
4471 it to =[-]=, which is considered to be an intermediate state.
4473 - {{{kbd(C-c C-x C-b)}}} (~org-toggle-checkbox~) ::
4475 #+kindex: C-c C-x C-b
4476 Toggle checkbox status or---with prefix argument---checkbox presence
4477 at point. With double prefix argument, set it to =[-]=, which is
4478 considered to be an intermediate state.
4480 - If there is an active region, toggle the first checkbox in the
4481 region and set all remaining boxes to the same status as the
4482 first. With a prefix argument, add or remove the checkbox for all
4483 items in the region.
4485 - If point is in a headline, toggle checkboxes in the region between
4486 this headline and the next---so /not/ the entire subtree.
4488 - If there is no active region, just toggle the checkbox at point.
4490 - {{{kbd(M-S-RET)}}} (~org-insert-todo-heading~) ::
4493 #+findex: org-insert-todo-heading
4494 Insert a new item with a checkbox. This works only if point is
4495 already in a plain list item (see [[*Plain Lists]]).
4497 - {{{kbd(C-c C-x o)}}} (~org-toggle-ordered-property~) ::
4500 #+findex: org-toggle-ordered-property
4501 #+vindex: org-track-ordered-property-with-tag
4502 Toggle the =ORDERED= property of the entry, to toggle if checkboxes
4503 must be checked off in sequence. A property is used for this
4504 behavior because this should be local to the current entry, not
4505 inherited like a tag. However, if you would like to /track/ the
4506 value of this property with a tag for better visibility, customize
4507 ~org-track-ordered-property-with-tag~.
4509 - {{{kbd(C-c #)}}} (~org-update-statistics-cookies~) ::
4512 #+findex: org-update-statistics-cookies
4513 Update the statistics cookie in the current outline entry. When
4514 called with a {{{kbd(C-u)}}} prefix, update the entire file.
4515 Checkbox statistic cookies are updated automatically if you toggle
4516 checkboxes with {{{kbd(C-c C-c)}}} and make new ones with
4517 {{{kbd(M-S-RET)}}}. TODO statistics cookies update when changing
4518 TODO states. If you delete boxes/entries or add/change them by
4519 hand, use this command to get things back into sync.
4523 :DESCRIPTION: Tagging headlines and matching sets of tags.
4526 #+cindex: headline tagging
4527 #+cindex: matching, tags
4528 #+cindex: sparse tree, tag based
4530 An excellent way to implement labels and contexts for
4531 cross-correlating information is to assign /tags/ to headlines. Org
4532 mode has extensive support for tags.
4534 #+vindex: org-tag-faces
4535 Every headline can contain a list of tags; they occur at the end of
4536 the headline. Tags are normal words containing letters, numbers, =_=,
4537 and =@=. Tags must be preceded and followed by a single colon, e.g.,
4538 =:work:=. Several tags can be specified, as in =:work:urgent:=. Tags
4539 by default are in bold face with the same color as the headline. You
4540 may specify special faces for specific tags using the variable
4541 ~org-tag-faces~, in much the same way as you can for TODO keywords
4542 (see [[*Faces for TODO keywords]]).
4546 :DESCRIPTION: Tags use the tree structure of an outline.
4548 #+cindex: tag inheritance
4549 #+cindex: inheritance, of tags
4550 #+cindex: sublevels, inclusion into tags match
4552 /Tags/ make use of the hierarchical structure of outline trees. If
4553 a heading has a certain tag, all subheadings inherit the tag as well.
4554 For example, in the list
4557 ,* Meeting with the French group :work:
4558 ,** Summary by Frank :boss:notes:
4559 ,*** TODO Prepare slides for him :action:
4562 #+texinfo: @noindent
4563 the final heading has the tags =work=, =boss=, =notes=, and =action=
4564 even though the final heading is not explicitly marked with those
4565 tags. You can also set tags that all entries in a file should inherit
4566 just as if these tags were defined in a hypothetical level zero that
4567 surrounds the entire file. Use a line like this[fn:53]
4569 #+cindex: @samp{FILETAGS}, keyword
4570 : #+FILETAGS: :Peter:Boss:Secret:
4572 #+vindex: org-use-tag-inheritance
4573 #+vindex: org-tags-exclude-from-inheritance
4574 To limit tag inheritance to specific tags, or to turn it off entirely,
4575 use the variables ~org-use-tag-inheritance~ and
4576 ~org-tags-exclude-from-inheritance~.
4578 #+vindex: org-tags-match-list-sublevels
4579 When a headline matches during a tags search while tag inheritance is
4580 turned on, all the sublevels in the same tree---for a simple match
4581 form---match as well[fn:54]. The list of matches may then become
4582 very long. If you only want to see the first tags match in a subtree,
4583 configure the variable ~org-tags-match-list-sublevels~ (not
4586 #+vindex: org-agenda-use-tag-inheritance
4587 Tag inheritance is relevant when the agenda search tries to match
4588 a tag, either in the ~tags~ or ~tags-todo~ agenda types. In other
4589 agenda types, ~org-use-tag-inheritance~ has no effect. Still, you may
4590 want to have your tags correctly set in the agenda, so that tag
4591 filtering works fine, with inherited tags. Set
4592 ~org-agenda-use-tag-inheritance~ to control this: the default value
4593 includes all agenda types, but setting this to ~nil~ can really speed
4594 up agenda generation.
4598 :DESCRIPTION: How to assign tags to a headline.
4600 #+cindex: setting tags
4601 #+cindex: tags, setting
4604 Tags can simply be typed into the buffer at the end of a headline.
4605 After a colon, {{{kbd(M-TAB)}}} offers completion on tags. There is
4606 also a special command for inserting tags:
4608 - {{{kbd(C-c C-q)}}} (~org-set-tags-command~) ::
4611 #+findex: org-set-tags-command
4612 #+cindex: completion, of tags
4613 #+vindex: org-tags-column
4614 Enter new tags for the current headline. Org mode either offers
4615 completion or a special single-key interface for setting tags, see
4616 below. After pressing {{{kbd(RET)}}}, the tags are inserted and
4617 aligned to ~org-tags-column~. When called with a {{{kbd(C-u)}}}
4618 prefix, all tags in the current buffer are aligned to that column,
4619 just to make things look nice. Tags are automatically realigned
4620 after promotion, demotion, and TODO state changes (see [[*Basic TODO
4623 - {{{kbd(C-c C-c)}}} (~org-set-tags-command~) ::
4626 When point is in a headline, this does the same as {{{kbd(C-c
4629 #+vindex: org-complete-tags-always-offer-all-agenda-tags
4630 #+vindex: org-tag-alist
4631 #+cindex: @samp{TAGS}, keyword
4632 Org supports tag insertion based on a /list of tags/. By default this
4633 list is constructed dynamically, containing all tags currently used in
4634 the buffer[fn:55]. You may also globally specify a hard list of tags
4635 with the variable ~org-tag-alist~. Finally you can set the default
4636 tags for a given file using the =TAGS= keyword, like
4639 ,#+TAGS: @work @home @tennisclub
4640 ,#+TAGS: laptop car pc sailboat
4643 If you have globally defined your preferred set of tags using the
4644 variable ~org-tag-alist~, but would like to use a dynamic tag list in
4645 a specific file, add an empty =TAGS= keyword to that file:
4649 #+vindex: org-tag-persistent-alist
4650 If you have a preferred set of tags that you would like to use in
4651 every file, in addition to those defined on a per-file basis by =TAGS=
4652 keyword, then you may specify a list of tags with the variable
4653 ~org-tag-persistent-alist~. You may turn this off on a per-file basis
4654 by adding a =STARTUP= keyword to that file:
4658 By default Org mode uses the standard minibuffer completion facilities
4659 for entering tags. However, it also implements another, quicker, tag
4660 selection method called /fast tag selection/. This allows you to
4661 select and deselect tags with just a single key press. For this to
4662 work well you should assign unique letters to most of your commonly
4663 used tags. You can do this globally by configuring the variable
4664 ~org-tag-alist~ in your Emacs init file. For example, you may find
4665 the need to tag many items in different files with =@home=. In this
4666 case you can set something like:
4668 #+begin_src emacs-lisp
4669 (setq org-tag-alist '(("@work" . ?w) ("@home" . ?h) ("laptop" . ?l)))
4672 If the tag is only relevant to the file you are working on, then you
4673 can instead set the =TAGS= keyword as:
4675 : #+TAGS: @work(w) @home(h) @tennisclub(t) laptop(l) pc(p)
4677 The tags interface shows the available tags in a splash window. If
4678 you want to start a new line after a specific tag, insert =\n= into
4681 : #+TAGS: @work(w) @home(h) @tennisclub(t) \n laptop(l) pc(p)
4683 #+texinfo: @noindent
4684 or write them in two lines:
4687 ,#+TAGS: @work(w) @home(h) @tennisclub(t)
4688 ,#+TAGS: laptop(l) pc(p)
4691 You can also group together tags that are mutually exclusive by using
4694 : #+TAGS: { @work(w) @home(h) @tennisclub(t) } laptop(l) pc(p)
4696 #+texinfo: @noindent
4697 you indicate that at most one of =@work=, =@home=, and =@tennisclub=
4698 should be selected. Multiple such groups are allowed.
4700 Do not forget to press {{{kbd(C-c C-c)}}} with point in one of these
4701 lines to activate any changes.
4703 To set these mutually exclusive groups in the variable
4704 ~org-tags-alist~, you must use the dummy tags ~:startgroup~ and
4705 ~:endgroup~ instead of the braces. Similarly, you can use ~:newline~
4706 to indicate a line break. The previous example would be set globally
4707 by the following configuration:
4709 #+begin_src emacs-lisp
4710 (setq org-tag-alist '((:startgroup . nil)
4711 ("@work" . ?w) ("@home" . ?h)
4712 ("@tennisclub" . ?t)
4714 ("laptop" . ?l) ("pc" . ?p)))
4717 If at least one tag has a selection key then pressing {{{kbd(C-c
4718 C-c)}}} automatically presents you with a special interface, listing
4719 inherited tags, the tags of the current headline, and a list of all
4720 valid tags with corresponding keys[fn:56].
4722 Pressing keys assigned to tags adds or removes them from the list of
4723 tags in the current line. Selecting a tag in a group of mutually
4724 exclusive tags turns off any other tag from that group.
4726 In this interface, you can also use the following special keys:
4731 Enter a tag in the minibuffer, even if the tag is not in the
4732 predefined list. You can complete on all tags present in the
4733 buffer. You can also add several tags: just separate them with
4739 Clear all tags for this line.
4744 Accept the modified set.
4749 Abort without installing changes.
4754 If {{{kbd(q)}}} is not assigned to a tag, it aborts like
4760 Turn off groups of mutually exclusive tags. Use this to (as an
4761 exception) assign several tags from such a group.
4766 Toggle auto-exit after the next change (see below). If you are
4767 using expert mode, the first {{{kbd(C-c)}}} displays the selection
4770 This method lets you assign tags to a headline with very few keys.
4771 With the above setup, you could clear the current tags and set
4772 =@home=, =laptop= and =pc= tags with just the following keys:
4773 {{{kbd(C-c C-c SPC h l p RET)}}}. Switching from =@home= to =@work=
4774 would be done with {{{kbd(C-c C-c w RET)}}} or alternatively with
4775 {{{kbd(C-c C-c C-c w)}}}. Adding the non-predefined tag =sarah= could
4776 be done with {{{kbd(C-c C-c TAB s a r a h RET)}}}.
4778 #+vindex: org-fast-tag-selection-single-key
4779 If you find that most of the time you need only a single key press to
4780 modify your list of tags, set the variable
4781 ~org-fast-tag-selection-single-key~. Then you no longer have to press
4782 {{{kbd(RET)}}} to exit fast tag selection---it exits after the first
4783 change. If you then occasionally need more keys, press {{{kbd(C-c)}}}
4784 to turn off auto-exit for the current tag selection process (in
4785 effect: start selection with {{{kbd(C-c C-c C-c)}}} instead of
4786 {{{kbd(C-c C-c)}}}). If you set the variable to the value ~expert~,
4787 the special window is not even shown for single-key tag selection, it
4788 comes up only when you press an extra {{{kbd(C-c)}}}.
4792 :DESCRIPTION: Create a hierarchy of tags.
4794 #+cindex: group tags
4795 #+cindex: tags, groups
4796 #+cindex: tags hierarchy
4798 Tags can be defined in hierarchies. A tag can be defined as a /group
4799 tag/ for a set of other tags. The group tag can be seen as the
4800 "broader term" for its set of tags. Defining multiple group tags and
4801 nesting them creates a tag hierarchy.
4803 One use-case is to create a taxonomy of terms (tags) that can be used
4804 to classify nodes in a document or set of documents.
4806 When you search for a group tag, it return matches for all members in
4807 the group and its subgroups. In an agenda view, filtering by a group
4808 tag displays or hide headlines tagged with at least one of the members
4809 of the group or any of its subgroups. This makes tag searches and
4810 filters even more flexible.
4812 You can set group tags by using brackets and inserting a colon between
4813 the group tag and its related tags---beware that all whitespaces are
4814 mandatory so that Org can parse this line correctly:
4816 : #+TAGS: [ GTD : Control Persp ]
4818 In this example, =GTD= is the group tag and it is related to two other
4819 tags: =Control=, =Persp=. Defining =Control= and =Persp= as group
4820 tags creates a hierarchy of tags:
4823 ,#+TAGS: [ Control : Context Task ]
4824 ,#+TAGS: [ Persp : Vision Goal AOF Project ]
4827 That can conceptually be seen as a hierarchy of tags:
4839 You can use the ~:startgrouptag~, ~:grouptags~ and ~:endgrouptag~
4840 keyword directly when setting ~org-tag-alist~ directly:
4842 #+begin_src emacs-lisp
4843 (setq org-tag-alist '((:startgrouptag)
4857 The tags in a group can be mutually exclusive if using the same group
4858 syntax as is used for grouping mutually exclusive tags together; using
4861 : #+TAGS: { Context : @Home @Work @Call }
4863 When setting ~org-tag-alist~ you can use ~:startgroup~ and ~:endgroup~
4864 instead of ~:startgrouptag~ and ~:endgrouptag~ to make the tags
4867 Furthermore, the members of a group tag can also be regular
4868 expressions, creating the possibility of a more dynamic and rule-based
4869 tag structure. The regular expressions in the group must be specified
4870 within curly brackets. Here is an expanded example:
4873 ,#+TAGS: [ Vision : {V@.+} ]
4874 ,#+TAGS: [ Goal : {G@.+} ]
4875 ,#+TAGS: [ AOF : {AOF@.+} ]
4876 ,#+TAGS: [ Project : {P@.+} ]
4879 Searching for the tag =Project= now lists all tags also including
4880 regular expression matches for =P@.+=, and similarly for tag searches
4881 on =Vision=, =Goal= and =AOF=. For example, this would work well for
4882 a project tagged with a common project-identifier, e.g.,
4886 #+findex: org-toggle-tags-groups
4887 #+vindex: org-group-tags
4888 If you want to ignore group tags temporarily, toggle group tags
4889 support with ~org-toggle-tags-groups~, bound to {{{kbd(C-c C-x q)}}}.
4890 If you want to disable tag groups completely, set ~org-group-tags~ to
4895 :DESCRIPTION: Searching for combinations of tags.
4897 #+cindex: tag searches
4898 #+cindex: searching for tags
4900 Once a system of tags has been set up, it can be used to collect
4901 related information into special lists.
4903 - {{{kbd(C-c / m)}}} or {{{kbd(C-c \)}}} (~org-match-sparse-tree~) ::
4907 #+findex: org-match-sparse-tree
4908 Create a sparse tree with all headlines matching a tags search.
4909 With a {{{kbd(C-u)}}} prefix argument, ignore headlines that are not
4912 - {{{kbd(M-x org-agenda m)}}} (~org-tags-view~) ::
4914 #+kindex: m @r{(Agenda dispatcher)}
4915 #+findex: org-tags-view
4916 Create a global list of tag matches from all agenda files. See
4917 [[*Matching tags and properties]].
4919 - {{{kbd(M-x org-agenda M)}}} (~org-tags-view~) ::
4921 #+kindex: M @r{(Agenda dispatcher)}
4922 #+vindex: org-tags-match-list-sublevels
4923 Create a global list of tag matches from all agenda files, but check
4924 only TODO items and force checking subitems (see the option
4925 ~org-tags-match-list-sublevels~).
4927 These commands all prompt for a match string which allows basic
4928 Boolean logic like =+boss+urgent-project1=, to find entries with tags
4929 =boss= and =urgent=, but not =project1=, or =Kathy|Sally= to find
4930 entries which are tagged, like =Kathy= or =Sally=. The full syntax of
4931 the search string is rich and allows also matching against TODO
4932 keywords, entry levels and properties. For a complete description
4933 with many examples, see [[*Matching tags and properties]].
4935 * Properties and Columns
4937 :DESCRIPTION: Storing information about an entry.
4939 #+cindex: properties
4941 A property is a key-value pair associated with an entry. Properties
4942 can be set so they are associated with a single entry, with every
4943 entry in a tree, or with every entry in an Org file.
4945 There are two main applications for properties in Org mode. First,
4946 properties are like tags, but with a value. Imagine maintaining
4947 a file where you document bugs and plan releases for a piece of
4948 software. Instead of using tags like =release_1=, =release_2=, you
4949 can use a property, say =Release=, that in different subtrees has
4950 different values, such as =1.0= or =2.0=. Second, you can use
4951 properties to implement (very basic) database capabilities in an Org
4952 buffer. Imagine keeping track of your music CDs, where properties
4953 could be things such as the album, artist, date of release, number of
4956 Properties can be conveniently edited and viewed in column view (see
4961 :DESCRIPTION: How properties are spelled out.
4963 #+cindex: property syntax
4964 #+cindex: drawer, for properties
4966 Properties are key--value pairs. When they are associated with
4967 a single entry or with a tree they need to be inserted into a special
4968 drawer (see [[*Drawers]]) with the name =PROPERTIES=, which has to be
4969 located right below a headline, and its planning line (see [[*Deadlines
4970 and Scheduling]]) when applicable. Each property is specified on
4971 a single line, with the key---surrounded by colons---first, and the
4972 value after it. Keys are case-insensitive. Here is an example:
4977 ,*** Goldberg Variations
4979 :Title: Goldberg Variations
4980 :Composer: J.S. Bach
4981 :Artist: Glenn Gould
4982 :Publisher: Deutsche Grammophon
4987 Depending on the value of ~org-use-property-inheritance~, a property
4988 set this way is associated either with a single entry, or with the
4989 sub-tree defined by the entry, see [[*Property Inheritance]].
4991 You may define the allowed values for a particular property =Xyz= by
4992 setting a property =Xyz_ALL=. This special property is /inherited/,
4993 so if you set it in a level 1 entry, it applies to the entire tree.
4994 When allowed values are defined, setting the corresponding property
4995 becomes easier and is less prone to typing errors. For the example
4996 with the CD collection, we can pre-define publishers and the number of
4997 disks in a box like this:
5002 :NDisks_ALL: 1 2 3 4
5003 :Publisher_ALL: "Deutsche Grammophon" Philips EMI
5007 If you want to set properties that can be inherited by any entry in
5008 a file, use a line like:
5010 #+cindex: @samp{_ALL} suffix, in properties
5011 #+cindex: @samp{PROPERTY}, keyword
5012 : #+PROPERTY: NDisks_ALL 1 2 3 4
5014 #+cindex: @samp{+} suffix, in properties
5015 If you want to add to the value of an existing property, append a =+=
5016 to the property name. The following results in the property =var=
5017 having the value =foo=1 bar=2=.
5020 ,#+PROPERTY: var foo=1
5021 ,#+PROPERTY: var+ bar=2
5024 It is also possible to add to the values of inherited properties. The
5025 following results in the =Genres= property having the value =Classic
5026 Baroque= under the =Goldberg Variations= subtree.
5034 ,*** Goldberg Variations
5036 :Title: Goldberg Variations
5037 :Composer: J.S. Bach
5038 :Artist: Glenn Gould
5039 :Publisher: Deutsche Grammophon
5045 Note that a property can only have one entry per drawer.
5047 #+vindex: org-global-properties
5048 Property values set with the global variable ~org-global-properties~
5049 can be inherited by all entries in all Org files.
5051 The following commands help to work with properties:
5053 #+attr_texinfo: :sep ,
5054 - {{{kbd(M-TAB)}}} (~pcomplete~) ::
5058 After an initial colon in a line, complete property keys. All keys
5059 used in the current file are offered as possible completions.
5061 - {{{kbd(C-c C-x p)}}} (~org-set-property~) ::
5064 #+findex: org-set-property
5065 Set a property. This prompts for a property name and a value. If
5066 necessary, the property drawer is created as well.
5068 - {{{kbd(C-u M-x org-insert-drawer)}}} ::
5070 #+findex: org-insert-drawer
5071 Insert a property drawer into the current entry. The drawer is
5072 inserted early in the entry, but after the lines with planning
5073 information like deadlines.
5075 - {{{kbd(C-c C-c)}}} (~org-property-action~) ::
5078 #+findex: org-property-action
5079 With point in a property drawer, this executes property commands.
5081 - {{{kbd(C-c C-c s)}}} (~org-set-property~) ::
5084 #+findex: org-set-property
5085 Set a property in the current entry. Both the property and the
5086 value can be inserted using completion.
5088 - {{{kbd(S-RIGHT)}}} (~org-property-next-allowed-values~), {{{kbd(S-LEFT)}}} (~org-property-previous-allowed-value~) ::
5092 Switch property at point to the next/previous allowed value.
5094 - {{{kbd(C-c C-c d)}}} (~org-delete-property~) ::
5097 #+findex: org-delete-property
5098 Remove a property from the current entry.
5100 - {{{kbd(C-c C-c D)}}} (~org-delete-property-globally~) ::
5103 #+findex: org-delete-property-globally
5104 Globally remove a property, from all entries in the current file.
5106 - {{{kbd(C-c C-c c)}}} (~org-compute-property-at-point~) ::
5109 #+findex: org-compute-property-at-point
5110 Compute the property at point, using the operator and scope from the
5111 nearest column format definition.
5113 ** Special Properties
5115 :DESCRIPTION: Access to other Org mode features.
5117 #+cindex: properties, special
5119 Special properties provide an alternative access method to Org mode
5120 features, like the TODO state or the priority of an entry, discussed
5121 in the previous chapters. This interface exists so that you can
5122 include these states in a column view (see [[*Column View]]), or to use
5123 them in queries. The following property names are special and should
5124 not be used as keys in the properties drawer:
5126 #+cindex: @samp{ALLTAGS}, special property
5127 #+cindex: @samp{BLOCKED}, special property
5128 #+cindex: @samp{CLOCKSUM}, special property
5129 #+cindex: @samp{CLOCKSUM_T}, special property
5130 #+cindex: @samp{CLOSED}, special property
5131 #+cindex: @samp{DEADLINE}, special property
5132 #+cindex: @samp{FILE}, special property
5133 #+cindex: @samp{ITEM}, special property
5134 #+cindex: @samp{PRIORITY}, special property
5135 #+cindex: @samp{SCHEDULED}, special property
5136 #+cindex: @samp{TAGS}, special property
5137 #+cindex: @samp{TIMESTAMP}, special property
5138 #+cindex: @samp{TIMESTAMP_IA}, special property
5139 #+cindex: @samp{TODO}, special property
5140 | =ALLTAGS= | All tags, including inherited ones. |
5141 | =BLOCKED= | ~t~ if task is currently blocked by children or siblings. |
5142 | =CATEGORY= | The category of an entry. |
5143 | =CLOCKSUM= | The sum of CLOCK intervals in the subtree. ~org-clock-sum~ |
5144 | | must be run first to compute the values in the current buffer. |
5145 | =CLOCKSUM_T= | The sum of CLOCK intervals in the subtree for today. |
5146 | | ~org-clock-sum-today~ must be run first to compute the |
5147 | | values in the current buffer. |
5148 | =CLOSED= | When was this entry closed? |
5149 | =DEADLINE= | The deadline time string, without the angular brackets. |
5150 | =FILE= | The filename the entry is located in. |
5151 | =ITEM= | The headline of the entry. |
5152 | =PRIORITY= | The priority of the entry, a string with a single letter. |
5153 | =SCHEDULED= | The scheduling timestamp, without the angular brackets. |
5154 | =TAGS= | The tags defined directly in the headline. |
5155 | =TIMESTAMP= | The first keyword-less timestamp in the entry. |
5156 | =TIMESTAMP_IA= | The first inactive timestamp in the entry. |
5157 | =TODO= | The TODO keyword of the entry. |
5159 ** Property Searches
5161 :DESCRIPTION: Matching property values.
5163 #+cindex: properties, searching
5164 #+cindex: searching, of properties
5166 To create sparse trees and special lists with selection based on
5167 properties, the same commands are used as for tag searches (see [[*Tag
5170 - {{{kbd(C-c / m)}}} or {{{kbd(C-c \)}}} (~org-match-sparse-tree~) ::
5174 #+findex: org-match-sparse-tree
5175 Create a sparse tree with all matching entries. With
5176 a {{{kbd(C-u)}}} prefix argument, ignore headlines that are not
5179 - {{{kbd(M-x org-agenda m)}}}, ~org-tags-view~ ::
5181 #+kindex: m @r{(Agenda dispatcher)}
5182 #+findex: org-tags-view
5183 Create a global list of tag/property matches from all agenda files.
5185 - {{{kbd(M-x org-agenda M)}}} (~org-tags-view~) ::
5187 #+kindex: M @r{(Agenda dispatcher)}
5188 #+vindex: org-tags-match-list-sublevels
5189 Create a global list of tag matches from all agenda files, but check
5190 only TODO items and force checking of subitems (see the option
5191 ~org-tags-match-list-sublevels~).
5193 The syntax for the search string is described in [[*Matching tags and
5196 There is also a special command for creating sparse trees based on a
5199 - {{{kbd(C-c / p)}}} ::
5202 Create a sparse tree based on the value of a property. This first
5203 prompts for the name of a property, and then for a value. A sparse
5204 tree is created with all entries that define this property with the
5205 given value. If you enclose the value in curly braces, it is
5206 interpreted as a regular expression and matched against the property
5209 ** Property Inheritance
5211 :DESCRIPTION: Passing values down a tree.
5213 #+cindex: properties, inheritance
5214 #+cindex: inheritance, of properties
5216 #+vindex: org-use-property-inheritance
5217 The outline structure of Org documents lends itself to an inheritance
5218 model of properties: if the parent in a tree has a certain property,
5219 the children can inherit this property. Org mode does not turn this
5220 on by default, because it can slow down property searches
5221 significantly and is often not needed. However, if you find
5222 inheritance useful, you can turn it on by setting the variable
5223 ~org-use-property-inheritance~. It may be set to ~t~ to make all
5224 properties inherited from the parent, to a list of properties that
5225 should be inherited, or to a regular expression that matches inherited
5226 properties. If a property has the value ~nil~, this is interpreted as
5227 an explicit un-define of the property, so that inheritance search
5228 stops at this value and returns ~nil~.
5230 Org mode has a few properties for which inheritance is hard-coded, at
5231 least for the special applications for which they are used:
5235 #+cindex: @samp{COLUMNS}, property
5236 The =COLUMNS= property defines the format of column view (see
5237 [[*Column View]]). It is inherited in the sense that the level where
5238 a =COLUMNS= property is defined is used as the starting point for
5239 a column view table, independently of the location in the subtree
5240 from where columns view is turned on.
5244 #+cindex: @samp{CATEGORY}, property
5245 For agenda view, a category set through a =CATEGORY= property
5246 applies to the entire subtree.
5250 #+cindex: @samp{ARCHIVE}, property
5251 For archiving, the =ARCHIVE= property may define the archive
5252 location for the entire subtree (see [[*Moving a tree to an archive
5257 #+cindex: @samp{LOGGING}, property
5258 The =LOGGING= property may define logging settings for an entry or
5259 a subtree (see [[*Tracking TODO state changes]]).
5263 :DESCRIPTION: Tabular viewing and editing.
5266 A great way to view and edit properties in an outline tree is /column
5267 view/. In column view, each outline node is turned into a table row.
5268 Columns in this table provide access to properties of the entries.
5269 Org mode implements columns by overlaying a tabular structure over the
5270 headline of each item. While the headlines have been turned into
5271 a table row, you can still change the visibility of the outline tree.
5272 For example, you get a compact table by switching to "contents"
5273 view---{{{kbd(S-TAB)}}} {{{kbd(S-TAB)}}}, or simply {{{kbd(c)}}}
5274 while column view is active---but you can still open, read, and edit
5275 the entry below each headline. Or, you can switch to column view
5276 after executing a sparse tree command and in this way get a table only
5277 for the selected items. Column view also works in agenda buffers (see
5278 [[*Agenda Views]]) where queries have collected selected items, possibly
5279 from a number of files.
5281 *** Defining columns
5283 :DESCRIPTION: The COLUMNS format property.
5285 #+cindex: column view, for properties
5286 #+cindex: properties, column view
5288 Setting up a column view first requires defining the columns. This is
5289 done by defining a column format line.
5291 **** Scope of column definitions
5293 :DESCRIPTION: Where defined, where valid?
5296 To define a column format for an entire file, use a line like:
5298 #+cindex: @samp{COLUMNS}, keyword
5299 : #+COLUMNS: %25ITEM %TAGS %PRIORITY %TODO
5301 To specify a format that only applies to a specific tree, add
5302 a =COLUMNS= property to the top node of that tree, for example:
5305 ,** Top node for columns view
5307 :COLUMNS: %25ITEM %TAGS %PRIORITY %TODO
5311 If a =COLUMNS= property is present in an entry, it defines columns for
5312 the entry itself, and for the entire subtree below it. Since the
5313 column definition is part of the hierarchical structure of the
5314 document, you can define columns on level 1 that are general enough
5315 for all sublevels, and more specific columns further down, when you
5316 edit a deeper part of the tree.
5318 **** Column attributes
5320 :DESCRIPTION: Appearance and content of a column.
5323 A column definition sets the attributes of a column. The general
5324 definition looks like this:
5326 : %[WIDTH]PROPERTY[(TITLE)][{SUMMARY-TYPE}]
5328 #+texinfo: @noindent
5329 Except for the percent sign and the property name, all items are
5330 optional. The individual parts have the following meaning:
5332 - {{{var(WIDTH)}}} ::
5334 An integer specifying the width of the column in characters. If
5335 omitted, the width is determined automatically.
5337 - {{{var(PROPERTY)}}} ::
5339 The property that should be edited in this column. Special
5340 properties representing meta data are allowed here as well (see
5341 [[*Special Properties]]).
5343 - {{{var(TITLE)}}} ::
5345 The header text for the column. If omitted, the property name is
5348 - {{{var(SUMMARY-TYPE)}}} ::
5350 The summary type. If specified, the column values for parent nodes
5351 are computed from the children[fn:57].
5353 Supported summary types are:
5355 | =+= | Sum numbers in this column. |
5356 | =+;%.1f= | Like =+=, but format result with =%.1f=. |
5357 | =$= | Currency, short for =+;%.2f=. |
5358 | =min= | Smallest number in column. |
5359 | =max= | Largest number. |
5360 | =mean= | Arithmetic mean of numbers. |
5361 | =X= | Checkbox status, =[X]= if all children are =[X]=. |
5362 | =X/= | Checkbox status, =[n/m]=. |
5363 | =X%= | Checkbox status, =[n%]=. |
5364 | =:= | Sum times, HH:MM, plain numbers are minutes. |
5365 | =:min= | Smallest time value in column. |
5366 | =:max= | Largest time value. |
5367 | =:mean= | Arithmetic mean of time values. |
5368 | =@min= | Minimum age[fn:58] (in days/hours/mins/seconds). |
5369 | =@max= | Maximum age (in days/hours/mins/seconds). |
5370 | =@mean= | Arithmetic mean of ages (in days/hours/mins/seconds). |
5371 | =est+= | Add low-high estimates. |
5373 #+vindex: org-columns-summary-types
5374 You can also define custom summary types by setting
5375 ~org-columns-summary-types~.
5377 The =est+= summary type requires further explanation. It is used for
5378 combining estimates, expressed as low-high ranges. For example,
5379 instead of estimating a particular task will take 5 days, you might
5380 estimate it as 5--6 days if you're fairly confident you know how much
5381 work is required, or 1--10 days if you do not really know what needs
5382 to be done. Both ranges average at 5.5 days, but the first represents
5383 a more predictable delivery.
5385 When combining a set of such estimates, simply adding the lows and
5386 highs produces an unrealistically wide result. Instead, =est+= adds
5387 the statistical mean and variance of the subtasks, generating a final
5388 estimate from the sum. For example, suppose you had ten tasks, each
5389 of which was estimated at 0.5 to 2 days of work. Straight addition
5390 produces an estimate of 5 to 20 days, representing what to expect if
5391 everything goes either extremely well or extremely poorly. In
5392 contrast, =est+= estimates the full job more realistically, at 10--15
5395 Here is an example for a complete columns definition, along with
5396 allowed values[fn:59].
5399 :COLUMNS: %25ITEM %9Approved(Approved?){X} %Owner %11Status \
5400 %10Time_Estimate{:} %CLOCKSUM %CLOCKSUM_T
5401 :Owner_ALL: Tammy Mark Karl Lisa Don
5402 :Status_ALL: "In progress" "Not started yet" "Finished" ""
5403 :Approved_ALL: "[ ]" "[X]"
5406 #+texinfo: @noindent
5407 The first column, =%25ITEM=, means the first 25 characters of the item
5408 itself, i.e., of the headline. You probably always should start the
5409 column definition with the =ITEM= specifier. The other specifiers
5410 create columns =Owner= with a list of names as allowed values, for
5411 =Status= with four different possible values, and for a checkbox field
5412 =Approved=. When no width is given after the =%= character, the
5413 column is exactly as wide as it needs to be in order to fully display
5414 all values. The =Approved= column does have a modified title
5415 (=Approved?=, with a question mark). Summaries are created for the
5416 =Time_Estimate= column by adding time duration expressions like HH:MM,
5417 and for the =Approved= column, by providing an =[X]= status if all
5418 children have been checked. The =CLOCKSUM= and =CLOCKSUM_T= columns
5419 are special, they lists the sums of CLOCK intervals in the subtree,
5420 either for all clocks or just for today.
5422 *** Using column view
5424 :DESCRIPTION: How to create and use column view.
5427 **** Turning column view on or off
5432 - {{{kbd(C-c C-x C-c)}}} (~org-columns~) ::
5434 #+kindex: C-c C-x C-c
5435 #+vindex: org-columns
5436 #+vindex: org-columns-default-format
5437 Turn on column view. If point is before the first headline in the
5438 file, column view is turned on for the entire file, using the
5439 =#+COLUMNS= definition. If point is somewhere inside the outline,
5440 this command searches the hierarchy, up from point, for a =COLUMNS=
5441 property that defines a format. When one is found, the column view
5442 table is established for the tree starting at the entry that
5443 contains the =COLUMNS= property. If no such property is found, the
5444 format is taken from the =#+COLUMNS= line or from the variable
5445 ~org-columns-default-format~, and column view is established for the
5446 current entry and its subtree.
5448 - {{{kbd(r)}}} or {{{kbd(g)}}} (~org-columns-redo~) ::
5452 #+findex: org-columns-redo
5453 Recreate the column view, to include recent changes made in the
5456 - {{{kbd(q)}}} (~org-columns-quit~) ::
5459 #+findex: org-columns-quit
5467 #+attr_texinfo: :sep and
5468 - {{{kbd(LEFT)}}}, {{{kbd(RIGHT)}}}, {{{kbd(UP)}}}, {{{kbd(DOWN)}}} ::
5470 Move through the column view from field to field.
5472 - {{{kbd(1..9\,0)}}} ::
5475 Directly select the Nth allowed value, {{{kbd(0)}}} selects the
5478 - {{{kbd(n)}}} or {{{kbd(S-RIGHT)}}} (~org-columns-next-allowed-value~) and {{{kbd(p)}}} or {{{kbd(S-LEFT)}}} (~org-columns-previous-allowed-value~) ::
5484 #+findex: org-columns-next-allowed-value
5485 #+findex: org-columns-previous-allowed-value
5486 Switch to the next/previous allowed value of the field. For this,
5487 you have to have specified allowed values for a property.
5489 - {{{kbd(e)}}} (~org-columns-edit-value~) ::
5492 #+findex: org-columns-edit-value
5493 Edit the property at point. For the special properties, this
5494 invokes the same interface that you normally use to change that
5495 property. For example, the tag completion or fast selection
5496 interface pops up when editing a =TAGS= property.
5498 - {{{kbd(C-c C-c)}}} (~org-columns-set-tags-or-toggle~) ::
5501 #+findex: org-columns-set-tags-or-toggle
5502 When there is a checkbox at point, toggle it.
5504 - {{{kbd(v)}}} (~org-columns-show-value~) ::
5507 #+findex: org-columns-show-value
5508 View the full value of this property. This is useful if the width
5509 of the column is smaller than that of the value.
5511 - {{{kbd(a)}}} (~org-columns-edit-allowed~) ::
5514 #+findex: org-columns-edit-allowed
5515 Edit the list of allowed values for this property. If the list is
5516 found in the hierarchy, the modified values is stored there. If no
5517 list is found, the new value is stored in the first entry that is
5518 part of the current column view.
5520 **** Modifying column view on-the-fly
5525 #+attr_texinfo: :sep and
5526 - {{{kbd(<)}}} (~org-columns-narrow~) and {{{kbd(>)}}} (~org-columns-widen~) ::
5530 #+findex: org-columns-narrow
5531 #+findex: org-columns-widen
5532 Make the column narrower/wider by one character.
5534 - {{{kbd(S-M-RIGHT)}}} (~org-columns-new~) ::
5537 #+findex: org-columns-new
5538 Insert a new column, to the left of the current column.
5540 - {{{kbd(S-M-LEFT)}}} (~org-columns-delete~) ::
5543 #+findex: org-columns-delete
5544 Delete the current column.
5546 *** Capturing column view
5548 :DESCRIPTION: A dynamic block for column view.
5551 Since column view is just an overlay over a buffer, it cannot be
5552 exported or printed directly. If you want to capture a column view,
5553 use a =columnview= dynamic block (see [[*Dynamic Blocks]]). The frame of
5554 this block looks like this:
5556 #+cindex: @samp{BEGIN columnview}
5559 ,#+BEGIN: columnview :hlines 1 :id "label"
5564 This dynamic block has the following parameters:
5568 This is the most important parameter. Column view is a feature that
5569 is often localized to a certain (sub)tree, and the capture block
5570 might be at a different location in the file. To identify the tree
5571 whose view to capture, you can use four values:
5575 Use the tree in which the capture block is located.
5579 Make a global view, including all headings in the file.
5581 - =file:FILENAME= ::
5583 Run column view at the top of the {{{var(FILENAME)}}} file.
5587 #+cindex: @samp{ID}, property
5588 Call column view in the tree that has an =ID= property with the
5589 value {{{var(LABEL)}}}. You can use {{{kbd(M-x org-id-copy)}}} to
5590 create a globally unique ID for the current entry and copy it to
5595 When ~t~, insert an hline after every line. When a number N, insert
5596 an hline before each headline with level ~<= N~.
5600 When non-~nil~, force column groups to get vertical lines.
5604 When set to a number, do not capture entries below this level.
5606 - =:skip-empty-rows= ::
5608 When non-~nil~, skip rows where the only non-empty specifier of
5609 the column view is =ITEM=.
5611 - =:exclude-tags= ::
5613 List of tags to exclude from column view table: entries with these
5614 tags will be excluded from the column view.
5618 When non-~nil~, indent each =ITEM= field according to its level.
5622 Specify a column attribute (see [[*Column attributes]]) for the dynamic
5625 The following commands insert or update the dynamic block:
5627 - {{{kbd(C-c C-x i)}}} (~org-insert-columns-dblock~) ::
5630 #+findex: org-insert-columns-dblock
5631 Insert a dynamic block capturing a column view. Prompt for the
5632 scope or ID of the view.
5634 - {{{kbd(C-c C-c)}}} {{{kbd(C-c C-x C-u)}}} (~org-dblock-update~) ::
5637 #+kindex: C-c C-x C-u
5638 #+findex: org-dblock-update
5639 Update dynamic block at point. point needs to be in the =#+BEGIN=
5640 line of the dynamic block.
5642 - {{{kbd(C-u C-c C-x C-u)}}} (~org-update-all-dblocks~) ::
5644 #+kindex: C-u C-c C-x C-u
5645 Update all dynamic blocks (see [[*Dynamic Blocks]]). This is useful if
5646 you have several clock table blocks, column-capturing blocks or
5647 other dynamic blocks in a buffer.
5649 You can add formulas to the column view table and you may add plotting
5650 instructions in front of the table---these survive an update of the
5651 block. If there is a =TBLFM= keyword after the table, the table is
5652 recalculated automatically after an update.
5654 An alternative way to capture and process property values into a table
5655 is provided by Eric Schulte's =org-collector.el=, which is
5656 a contributed package[fn:60]. It provides a general API to collect
5657 properties from entries in a certain scope, and arbitrary Lisp
5658 expressions to process these values before inserting them into a table
5663 :DESCRIPTION: Making items useful for planning.
5668 #+cindex: date stamp
5670 To assist project planning, TODO items can be labeled with a date
5671 and/or a time. The specially formatted string carrying the date and
5672 time information is called a /timestamp/ in Org mode. This may be
5673 a little confusing because timestamp is often used as indicating when
5674 something was created or last changed. However, in Org mode this term
5675 is used in a much wider sense.
5677 ** Timestamps, Deadlines and Scheduling
5679 :DESCRIPTION: Assigning a time to a tree entry.
5680 :ALT_TITLE: Timestamps
5682 #+cindex: timestamps
5683 #+cindex: ranges, time
5684 #+cindex: date stamps
5686 #+cindex: scheduling
5688 A timestamp is a specification of a date (possibly with a time or
5689 a range of times) in a special format, either =<2003-09-16 Tue>= or
5690 =<2003-09-16 Tue 09:39>= or =<2003-09-16 Tue 12:00-12:30>=[fn:61].
5691 A timestamp can appear anywhere in the headline or body of an Org tree
5692 entry. Its presence causes entries to be shown on specific dates in
5693 the agenda (see [[*Weekly/daily agenda]]). We distinguish:
5695 - Plain timestamp; Event; Appointment ::
5698 #+cindex: appointment
5699 A simple timestamp just assigns a date/time to an item. This is
5700 just like writing down an appointment or event in a paper agenda.
5701 In the agenda display, the headline of an entry associated with
5702 a plain timestamp is shown exactly on that date.
5705 ,* Meet Peter at the movies
5706 <2006-11-01 Wed 19:15>
5707 ,* Discussion on climate change
5708 <2006-11-02 Thu 20:00-22:00>
5711 - Timestamp with repeater interval ::
5713 #+cindex: timestamp, with repeater interval
5714 A timestamp may contain a /repeater interval/, indicating that it
5715 applies not only on the given date, but again and again after
5716 a certain interval of N days (d), weeks (w), months (m), or years
5717 (y). The following shows up in the agenda every Wednesday:
5720 ,* Pick up Sam at school
5721 <2007-05-16 Wed 12:30 +1w>
5724 - Diary-style sexp entries ::
5726 #+cindex: diary style timestamps
5727 #+cindex: sexp timestamps
5728 For more complex date specifications, Org mode supports using the
5729 special sexp diary entries implemented in the Emacs calendar/diary
5730 package[fn:62]. For example, with optional time:
5733 ,* 22:00-23:00 The nerd meeting on every 2nd Thursday of the month
5734 <%%(diary-float t 4 2)>
5737 - Time/Date range ::
5740 #+cindex: date range
5741 Two timestamps connected by =--= denote a range. The headline is
5742 shown on the first and last day of the range, and on any dates that
5743 are displayed and fall in the range. Here is an example:
5746 ,** Meeting in Amsterdam
5747 <2004-08-23 Mon>--<2004-08-26 Thu>
5750 - Inactive timestamp ::
5752 #+cindex: timestamp, inactive
5753 #+cindex: inactive timestamp
5754 Just like a plain timestamp, but with square brackets instead of
5755 angular ones. These timestamps are inactive in the sense that they
5756 do /not/ trigger an entry to show up in the agenda.
5759 ,* Gillian comes late for the fifth time
5763 ** Creating Timestamps
5765 :DESCRIPTION: Commands to insert timestamps.
5768 For Org mode to recognize timestamps, they need to be in the specific
5769 format. All commands listed below produce timestamps in the correct
5772 #+attr_texinfo: :sep ,
5773 - {{{kbd(C-c .)}}} (~org-time-stamp~) ::
5776 #+findex: org-time-stamp
5777 Prompt for a date and insert a corresponding timestamp. When point
5778 is at an existing timestamp in the buffer, the command is used to
5779 modify this timestamp instead of inserting a new one. When this
5780 command is used twice in succession, a time range is inserted.
5783 #+vindex: org-time-stamp-rounding-minutes
5784 When called with a prefix argument, use the alternative format which
5785 contains date and time. The default time can be rounded to
5786 multiples of 5 minutes. See the option
5787 ~org-time-stamp-rounding-minutes~.
5789 #+kindex: C-u C-u C-c .
5790 With two prefix arguments, insert an active timestamp with the
5791 current time without prompting.
5793 - {{{kbd(C-c !)}}} (~org-time-stamp-inactive~) ::
5797 #+kindex: C-u C-u C-c !
5798 #+findex: org-time-stamp-inactive
5799 Like {{{kbd(C-c .)}}}, but insert an inactive timestamp that does
5800 not cause an agenda entry.
5802 - {{{kbd(C-c C-c)}}} ::
5805 Normalize timestamp, insert or fix day name if missing or wrong.
5807 - {{{kbd(C-c <)}}} (~org-date-from-calendar~) ::
5810 #+findex: org-date-from-calendar
5811 Insert a timestamp corresponding to point date in the calendar.
5813 - {{{kbd(C-c >)}}} (~org-goto-calendar~) ::
5816 #+findex: org-goto-calendar
5817 Access the Emacs calendar for the current date. If there is
5818 a timestamp in the current line, go to the corresponding date
5821 - {{{kbd(C-c C-o)}}} (~org-open-at-point~) ::
5824 #+findex: org-open-at-point
5825 Access the agenda for the date given by the timestamp or -range at
5826 point (see [[*Weekly/daily agenda]]).
5828 - {{{kbd(S-LEFT)}}} (~org-timestamp-down-day~), {{{kbd(S-RIGHT)}}} (~org-timestamp-up-day~) ::
5832 #+findex: org-timestamp-down-day
5833 #+findex: org-timestamp-up-day
5834 Change date at point by one day. These key bindings conflict with
5835 shift-selection and related modes (see [[*Packages that conflict with
5838 - {{{kbd(S-UP)}}} (~org-timestamp-up~), {{{kbd(S-DOWN)}}} (~org-timestamp-down~) ::
5842 On the beginning or enclosing bracket of a timestamp, change its
5843 type. Within a timestamp, change the item under point. Point can
5844 be on a year, month, day, hour or minute. When the timestamp
5845 contains a time range like =15:30-16:30=, modifying the first time
5846 also shifts the second, shifting the time block with constant
5847 length. To change the length, modify the second time. Note that if
5848 point is in a headline and not at a timestamp, these same keys
5849 modify the priority of an item (see [[*Priorities]]). The key bindings
5850 also conflict with shift-selection and related modes (see [[*Packages
5851 that conflict with Org mode]]).
5853 - {{{kbd(C-c C-y)}}} (~org-evaluate-time-range~) ::
5856 #+findex: org-evaluate-time-range
5857 #+cindex: evaluate time range
5858 Evaluate a time range by computing the difference between start and
5859 end. With a prefix argument, insert result after the time range (in
5860 a table: into the following column).
5862 *** The date/time prompt
5864 :DESCRIPTION: How Org mode helps you enter dates and times.
5866 #+cindex: date, reading in minibuffer
5867 #+cindex: time, reading in minibuffer
5869 #+vindex: org-read-date-prefer-future
5870 When Org mode prompts for a date/time, the default is shown in default
5871 date/time format, and the prompt therefore seems to ask for a specific
5872 format. But it in fact accepts date/time information in a variety of
5873 formats. Generally, the information should start at the beginning of
5874 the string. Org mode finds whatever information is in there and
5875 derives anything you have not specified from the /default date and
5876 time/. The default is usually the current date and time, but when
5877 modifying an existing timestamp, or when entering the second stamp of
5878 a range, it is taken from the stamp in the buffer. When filling in
5879 information, Org mode assumes that most of the time you want to enter
5880 a date in the future: if you omit the month/year and the given
5881 day/month is /before/ today, it assumes that you mean a future
5882 date[fn:63]. If the date has been automatically shifted into the
5883 future, the time prompt shows this with =(=>F)=.
5885 For example, let's assume that today is *June 13, 2006*. Here is how
5886 various inputs are interpreted, the items filled in by Org mode are in
5889 | =3-2-5= | \rArr{} 2003-02-05 |
5890 | =2/5/3= | \rArr{} 2003-02-05 |
5891 | =14= | \rArr{} *2006*-*06*-14 |
5892 | =12= | \rArr{} *2006*-*07*-12 |
5893 | =2/5= | \rArr{} *2007*-02-05 |
5894 | =Fri= | \rArr{} nearest Friday (default date or later) |
5895 | =sep 15= | \rArr{} *2006*-09-15 |
5896 | =feb 15= | \rArr{} *2007*-02-15 |
5897 | =sep 12 9= | \rArr{} 2009-09-12 |
5898 | =12:45= | \rArr{} *2006*-*06*-*13* 12:45 |
5899 | =22 sept 0:34= | \rArr{} *2006*-09-22 0:34 |
5900 | =w4= | \rArr{} ISO week for of the current year *2006* |
5901 | =2012 w4 fri= | \rArr{} Friday of ISO week 4 in 2012 |
5902 | =2012-w04-5= | \rArr{} Same as above |
5904 Furthermore you can specify a relative date by giving, as the /first/
5905 thing in the input: a plus/minus sign, a number and a letter---=d=,
5906 =w=, =m= or =y=---to indicate change in days, weeks, months, or
5907 years. With a single plus or minus, the date is always relative to
5908 today. With a double plus or minus, it is relative to the default
5909 date. If instead of a single letter, you use the abbreviation of day
5910 name, the date is the Nth such day, e.g.:
5912 | =+0= | \rArr{} today |
5913 | =.= | \rArr{} today |
5914 | =+4d= | \rArr{} four days from today |
5915 | =+4= | \rArr{} same as +4d |
5916 | =+2w= | \rArr{} two weeks from today |
5917 | =++5= | \rArr{} five days from default date |
5918 | =+2tue= | \rArr{} second Tuesday from now |
5920 #+vindex: parse-time-months
5921 #+vindex: parse-time-weekdays
5922 The function understands English month and weekday abbreviations. If
5923 you want to use un-abbreviated names and/or other languages, configure
5924 the variables ~parse-time-months~ and ~parse-time-weekdays~.
5926 #+vindex: org-read-date-force-compatible-dates
5927 Not all dates can be represented in a given Emacs implementation. By
5928 default Org mode forces dates into the compatibility range 1970--2037
5929 which works on all Emacs implementations. If you want to use dates
5930 outside of this range, read the docstring of the variable
5931 ~org-read-date-force-compatible-dates~.
5933 You can specify a time range by giving start and end times or by
5934 giving a start time and a duration (in HH:MM format). Use one or two
5935 dash(es) as the separator in the former case and use =+= as the
5936 separator in the latter case, e.g.:
5938 | =11am-1:15pm= | \rArr{} 11:00-13:15 |
5939 | =11am--1:15pm= | \rArr{} same as above |
5940 | =11am+2:15= | \rArr{} same as above |
5942 #+cindex: calendar, for selecting date
5943 #+vindex: org-popup-calendar-for-date-prompt
5944 Parallel to the minibuffer prompt, a calendar is popped up[fn:64].
5945 When you exit the date prompt, either by clicking on a date in the
5946 calendar, or by pressing {{{kbd(RET)}}}, the date selected in the
5947 calendar is combined with the information entered at the prompt. You
5948 can control the calendar fully from the minibuffer:
5962 #+attr_texinfo: :columns 0.25 0.55
5963 | {{{kbd(RET)}}} | Choose date at point in calendar. |
5964 | {{{kbd(mouse-1)}}} | Select date by clicking on it. |
5965 | {{{kbd(S-RIGHT)}}} | One day forward. |
5966 | {{{kbd(S-LEFT)}}} | One day backward. |
5967 | {{{kbd(S-DOWN)}}} | One week forward. |
5968 | {{{kbd(S-UP)}}} | One week backward. |
5969 | {{{kbd(M-S-RIGHT)}}} | One month forward. |
5970 | {{{kbd(M-S-LEFT)}}} | One month backward. |
5971 | {{{kbd(>)}}} | Scroll calendar forward by one month. |
5972 | {{{kbd(<)}}} | Scroll calendar backward by one month. |
5973 | {{{kbd(M-v)}}} | Scroll calendar forward by 3 months. |
5974 | {{{kbd(C-v)}}} | Scroll calendar backward by 3 months. |
5976 #+vindex: org-read-date-display-live
5977 The actions of the date/time prompt may seem complex, but I assure you
5978 they will grow on you, and you will start getting annoyed by pretty
5979 much any other way of entering a date/time out there. To help you
5980 understand what is going on, the current interpretation of your input
5981 is displayed live in the minibuffer[fn:65].
5983 *** Custom time format
5985 :DESCRIPTION: Making dates look different.
5987 #+cindex: custom date/time format
5988 #+cindex: time format, custom
5989 #+cindex: date format, custom
5991 #+vindex: org-display-custom-times
5992 #+vindex: org-time-stamp-custom-formats
5993 Org mode uses the standard ISO notation for dates and times as it is
5994 defined in ISO 8601. If you cannot get used to this and require
5995 another representation of date and time to keep you happy, you can get
5996 it by customizing the variables ~org-display-custom-times~ and
5997 ~org-time-stamp-custom-formats~.
5999 - {{{kbd(C-c C-x C-t)}}} (~org-toggle-time-stamp-overlays~) ::
6001 #+kindex: C-c C-x C-t
6002 #+findex: org-toggle-time-stamp-overlays
6003 Toggle the display of custom formats for dates and times.
6005 Org mode needs the default format for scanning, so the custom
6006 date/time format does not /replace/ the default format. Instead, it
6007 is put /over/ the default format using text properties. This has the
6008 following consequences:
6010 - You cannot place point onto a timestamp anymore, only before or
6013 - The {{{kbd(S-UP)}}} and {{{kbd(S-DOWN)}}} keys can no longer be used
6014 to adjust each component of a timestamp. If point is at the
6015 beginning of the stamp, {{{kbd(S-UP)}}} and {{{kbd(S-DOWN)}}} change
6016 the stamp by one day, just like {{{kbd(S-LEFT)}}}
6017 {{{kbd(S-RIGHT)}}}. At the end of the stamp, change the time by one
6020 - If the timestamp contains a range of clock times or a repeater,
6021 these are not overlaid, but remain in the buffer as they were.
6023 - When you delete a timestamp character-by-character, it only
6024 disappears from the buffer after /all/ (invisible) characters
6025 belonging to the ISO timestamp have been removed.
6027 - If the custom timestamp format is longer than the default and you
6028 are using dates in tables, table alignment will be messed up. If
6029 the custom format is shorter, things do work as expected.
6031 ** Deadlines and Scheduling
6033 :DESCRIPTION: Planning your work.
6036 A timestamp may be preceded by special keywords to facilitate
6037 planning. Both the timestamp and the keyword have to be positioned
6038 immediately after the task they refer to.
6042 #+cindex: @samp{DEADLINE} marker
6043 Meaning: the task (most likely a TODO item, though not necessarily)
6044 is supposed to be finished on that date.
6046 #+vindex: org-deadline-warning-days
6047 On the deadline date, the task is listed in the agenda. In
6048 addition, the agenda for /today/ carries a warning about the
6049 approaching or missed deadline, starting ~org-deadline-warning-days~
6050 before the due date, and continuing until the entry is marked DONE.
6054 ,*** TODO write article about the Earth for the Guide
6055 DEADLINE: <2004-02-29 Sun>
6056 The editor in charge is [[bbdb:Ford Prefect]]
6059 #+vindex: org-agenda-skip-deadline-prewarning-if-scheduled
6060 You can specify a different lead time for warnings for a specific
6061 deadlines using the following syntax. Here is an example with
6062 a warning period of 5 days =DEADLINE: <2004-02-29 Sun -5d>=. This
6063 warning is deactivated if the task gets scheduled and you set
6064 ~org-agenda-skip-deadline-prewarning-if-scheduled~ to ~t~.
6068 #+cindex: @samp{SCHEDULED} marker
6069 Meaning: you are planning to start working on that task on the given
6072 #+vindex: org-agenda-skip-scheduled-if-done
6073 The headline is listed under the given date[fn:66]. In addition,
6074 a reminder that the scheduled date has passed is present in the
6075 compilation for /today/, until the entry is marked DONE, i.e., the
6076 task is automatically forwarded until completed.
6079 ,*** TODO Call Trillian for a date on New Years Eve.
6080 SCHEDULED: <2004-12-25 Sat>
6083 #+vindex: org-scheduled-delay-days
6084 #+vindex: org-agenda-skip-scheduled-delay-if-deadline
6085 If you want to /delay/ the display of this task in the agenda, use
6086 =SCHEDULED: <2004-12-25 Sat -2d>=: the task is still scheduled on
6087 the 25th but will appear two days later. In case the task contains
6088 a repeater, the delay is considered to affect all occurrences; if
6089 you want the delay to only affect the first scheduled occurrence of
6090 the task, use =--2d= instead. See ~org-scheduled-delay-days~ and
6091 ~org-agenda-skip-scheduled-delay-if-deadline~ for details on how to
6092 control this globally or per agenda.
6094 #+attr_texinfo: :tag Important
6096 Scheduling an item in Org mode should /not/ be understood in the
6097 same way that we understand /scheduling a meeting/. Setting a date
6098 for a meeting is just a simple appointment, you should mark this
6099 entry with a simple plain timestamp, to get this item shown on the
6100 date where it applies. This is a frequent misunderstanding by Org
6101 users. In Org mode, /scheduling/ means setting a date when you want
6102 to start working on an action item.
6105 You may use timestamps with repeaters in scheduling and deadline
6106 entries. Org mode issues early and late warnings based on the
6107 assumption that the timestamp represents the /nearest instance/ of the
6108 repeater. However, the use of diary S-exp entries like
6110 : <%%(diary-float t 42)>
6112 #+texinfo: @noindent
6113 in scheduling and deadline timestamps is limited. Org mode does not
6114 know enough about the internals of each S-exp function to issue early
6115 and late warnings. However, it shows the item on each day where the
6116 S-exp entry matches.
6118 *** Inserting deadlines or schedules
6120 :DESCRIPTION: Planning items.
6121 :ALT_TITLE: Inserting deadline/schedule
6124 The following commands allow you to quickly insert a deadline or to
6125 schedule an item:[fn:67]
6127 - {{{kbd(C-c C-d)}}} (~org-deadline~) ::
6130 #+findex: org-deadline
6131 #+vindex: org-log-redeadline
6132 Insert =DEADLINE= keyword along with a stamp. The insertion happens
6133 in the line directly following the headline. Remove any =CLOSED=
6134 timestamp . When called with a prefix argument, also remove any
6135 existing deadline from the entry. Depending on the variable
6136 ~org-log-redeadline~, take a note when changing an existing
6139 - {{{kbd(C-c C-s)}}} (~org-schedule~) ::
6142 #+findex: org-schedule
6143 #+vindex: org-log-reschedule
6144 Insert =SCHEDULED= keyword along with a stamp. The insertion
6145 happens in the line directly following the headline. Remove any
6146 =CLOSED= timestamp. When called with a prefix argument, also remove
6147 the scheduling date from the entry. Depending on the variable
6148 ~org-log-reschedule~, take a note when changing an existing
6149 scheduling time[fn:69].
6151 - {{{kbd(C-c C-x C-k)}}} (~org-mark-entry-for-agenda-action~) ::
6153 #+kindex: C-c C-x C-k
6156 #+findex: org-mark-entry-for-agenda-action
6157 Mark the current entry for agenda action. After you have marked the
6158 entry like this, you can open the agenda or the calendar to find an
6159 appropriate date. With point on the selected date, press {{{kbd(k
6160 s)}}} or {{{kbd(k d)}}} to schedule the marked item.
6162 - {{{kbd(C-c / d)}}} (~org-check-deadlines~) ::
6165 #+findex: org-check-deadlines
6166 #+cindex: sparse tree, for deadlines
6167 #+vindex: org-deadline-warning-days
6168 Create a sparse tree with all deadlines that are either past-due, or
6169 which will become due within ~org-deadline-warning-days~. With
6170 {{{kbd(C-u)}}} prefix, show all deadlines in the file. With
6171 a numeric prefix, check that many days. For example, {{{kbd(C-1 C-c
6172 / d)}}} shows all deadlines due tomorrow.
6174 - {{{kbd(C-c / b)}}} (~org-check-before-date~) ::
6177 #+findex: org-check-before-date
6178 Sparse tree for deadlines and scheduled items before a given date.
6180 - {{{kbd(C-c / a)}}} (~org-check-after-date~) ::
6183 #+findex: org-check-after-date
6184 Sparse tree for deadlines and scheduled items after a given date.
6186 Note that ~org-schedule~ and ~org-deadline~ supports setting the date
6187 by indicating a relative time e.g., =+1d= sets the date to the next
6188 day after today, and =--1w= sets the date to the previous week before
6189 any current timestamp.
6193 :DESCRIPTION: Items that show up again and again.
6195 #+cindex: tasks, repeated
6196 #+cindex: repeated tasks
6198 Some tasks need to be repeated again and again. Org mode helps to
6199 organize such tasks using a so-called repeater in a =DEADLINE=,
6200 =SCHEDULED=, or plain timestamps[fn:70]. In the following example:
6203 ,** TODO Pay the rent
6204 DEADLINE: <2005-10-01 Sat +1m>
6207 #+texinfo: @noindent
6208 the =+1m= is a repeater; the intended interpretation is that the task
6209 has a deadline on =<2005-10-01>= and repeats itself every (one) month
6210 starting from that time. You can use yearly, monthly, weekly, daily
6211 and hourly repeat cookies by using the =y=, =w=, =m=, =d= and =h=
6212 letters. If you need both a repeater and a special warning period in
6213 a deadline entry, the repeater should come first and the warning
6216 : DEADLINE: <2005-10-01 Sat +1m -3d>
6218 #+vindex: org-todo-repeat-to-state
6219 Deadlines and scheduled items produce entries in the agenda when they
6220 are over-due, so it is important to be able to mark such an entry as
6221 DONE once you have done so. When you mark a =DEADLINE= or a
6222 =SCHEDULED= with the TODO keyword =DONE=, it no longer produces
6223 entries in the agenda. The problem with this is, however, is that
6224 then also the /next/ instance of the repeated entry will not be
6225 active. Org mode deals with this in the following way: when you try
6226 to mark such an entry DONE, using {{{kbd(C-c C-t)}}}, it shifts the
6227 base date of the repeating timestamp by the repeater interval, and
6228 immediately sets the entry state back to TODO[fn:71]. In the example
6229 above, setting the state to DONE would actually switch the date like
6233 ,** TODO Pay the rent
6234 DEADLINE: <2005-11-01 Tue +1m>
6237 To mark a task with a repeater as DONE, use {{{kbd(C-- 1 C-c C-t)}}},
6238 i.e., ~org-todo~ with a numeric prefix argument of =-1=.
6240 #+vindex: org-log-repeat
6241 A timestamp[fn:72] is added under the deadline, to keep a record that
6242 you actually acted on the previous instance of this deadline.
6244 As a consequence of shifting the base date, this entry is no longer
6245 visible in the agenda when checking past dates, but all future
6246 instances will be visible.
6248 With the =+1m= cookie, the date shift is always exactly one month. So
6249 if you have not paid the rent for three months, marking this entry
6250 DONE still keeps it as an overdue deadline. Depending on the task,
6251 this may not be the best way to handle it. For example, if you forgot
6252 to call your father for 3 weeks, it does not make sense to call him
6253 3 times in a single day to make up for it. Finally, there are tasks
6254 like changing batteries which should always repeat a certain time
6255 /after/ the last time you did it. For these tasks, Org mode has
6256 special repeaters =++= and =.+=. For example:
6259 ,** TODO Call Father
6260 DEADLINE: <2008-02-10 Sun ++1w>
6261 Marking this DONE shifts the date by at least one week, but also
6262 by as many weeks as it takes to get this date into the future.
6263 However, it stays on a Sunday, even if you called and marked it
6266 ,** TODO Empty kitchen trash
6267 DEADLINE: <2008-02-08 Fri 20:00 ++1d>
6268 Marking this DONE shifts the date by at least one day, and also
6269 by as many days as it takes to get the timestamp into the future.
6270 Since there is a time in the timestamp, the next deadline in the
6271 future will be on today's date if you complete the task before
6274 ,** TODO Check the batteries in the smoke detectors
6275 DEADLINE: <2005-11-01 Tue .+1m>
6276 Marking this DONE will shift the date to one month after today.
6279 #+vindex: org-agenda-skip-scheduled-if-deadline-is-shown
6280 You may have both scheduling and deadline information for a specific
6281 task. If the repeater is set for the scheduling information only, you
6282 probably want the repeater to be ignored after the deadline. If so,
6283 set the variable ~org-agenda-skip-scheduled-if-deadline-is-shown~ to
6284 ~repeated-after-deadline~. However, any scheduling information
6285 without a repeater is no longer relevant once the task is done, and
6286 thus, removed upon repeating the task. If you want both scheduling
6287 and deadline information to repeat after the same interval, set the
6288 same repeater for both timestamps.
6290 An alternative to using a repeater is to create a number of copies of
6291 a task subtree, with dates shifted in each copy. The command
6292 {{{kbd(C-c C-x c)}}} was created for this purpose; it is described in
6293 [[*Structure Editing]].
6295 ** Clocking Work Time
6297 :DESCRIPTION: Tracking how long you spend on a task.
6299 #+cindex: clocking time
6300 #+cindex: time clocking
6302 Org mode allows you to clock the time you spend on specific tasks in
6303 a project. When you start working on an item, you can start the
6304 clock. When you stop working on that task, or when you mark the task
6305 done, the clock is stopped and the corresponding time interval is
6306 recorded. It also computes the total time spent on each
6307 subtree[fn:73] of a project. And it remembers a history or tasks
6308 recently clocked, to that you can jump quickly between a number of
6309 tasks absorbing your time.
6311 To save the clock history across Emacs sessions, use:
6313 #+begin_src emacs-lisp
6314 (setq org-clock-persist 'history)
6315 (org-clock-persistence-insinuate)
6318 #+vindex: org-clock-persist
6319 When you clock into a new task after resuming Emacs, the incomplete
6320 clock[fn:74] is retrieved (see [[*Resolving idle time]]) and you are
6321 prompted about what to do with it.
6323 *** Clocking commands
6325 :DESCRIPTION: Starting and stopping a clock.
6328 #+attr_texinfo: :sep ,
6329 - {{{kbd(C-c C-x C-i)}}} (~org-clock-in~) ::
6331 #+kindex: C-c C-x C-i
6332 #+findex: org-clock-in
6333 #+vindex: org-clock-into-drawer
6334 #+vindex: org-clock-continuously
6335 #+cindex: @samp{LOG_INTO_DRAWER}, property
6336 Start the clock on the current item (clock-in). This inserts the
6337 CLOCK keyword together with a timestamp. If this is not the first
6338 clocking of this item, the multiple CLOCK lines are wrapped into
6339 a =LOGBOOK= drawer (see also the variable ~org-clock-into-drawer~).
6340 You can also overrule the setting of this variable for a subtree by
6341 setting a =CLOCK_INTO_DRAWER= or =LOG_INTO_DRAWER= property. When
6342 called with a {{{kbd(C-u)}}} prefix argument, select the task from
6343 a list of recently clocked tasks. With two {{{kbd(C-u C-u)}}}
6344 prefixes, clock into the task at point and mark it as the default
6345 task; the default task is always be available with letter
6346 {{{kbd(d)}}} when selecting a clocking task. With three {{{kbd(C-u
6347 C-u C-u)}}} prefixes, force continuous clocking by starting the
6348 clock when the last clock stopped.
6350 #+cindex: @samp{CLOCK_MODELINE_TOTAL}, property
6351 #+cindex: @samp{LAST_REPEAT}, property
6352 #+vindex: org-clock-mode-line-total
6353 #+vindex: org-clock-in-prepare-hook
6354 While the clock is running, Org shows the current clocking time in
6355 the mode line, along with the title of the task. The clock time
6356 shown is all time ever clocked for this task and its children. If
6357 the task has an effort estimate (see [[*Effort Estimates]]), the mode
6358 line displays the current clocking time against it[fn:76]. If the
6359 task is a repeating one (see [[*Repeated tasks]]), show only the time
6360 since the last reset of the task[fn:77]. You can exercise more
6361 control over show time with the =CLOCK_MODELINE_TOTAL= property. It
6362 may have the values =current= to show only the current clocking
6363 instance, =today= to show all time clocked on this tasks today---see
6364 also the variable ~org-extend-today-until~, ~all~ to include all
6365 time, or ~auto~ which is the default[fn:78]. Clicking with
6366 {{{kbd(mouse-1)}}} onto the mode line entry pops up a menu with
6369 - {{{kbd(C-c C-x C-o)}}} (~org-clock-out~) ::
6371 #+kindex: C-c C-x C-o
6372 #+findex: org-clock-out
6373 #+vindex: org-log-note-clock-out
6374 Stop the clock (clock-out). This inserts another timestamp at the
6375 same location where the clock was last started. It also directly
6376 computes the resulting time in inserts it after the time range as
6377 ==>HH:MM=. See the variable ~org-log-note-clock-out~ for the
6378 possibility to record an additional note together with the clock-out
6381 - {{{kbd(C-c C-x C-x)}}} (~org-clock-in-last~) ::
6383 #+kindex: C-c C-x C-x
6384 #+findex: org-clock-in-last
6385 #+vindex: org-clock-continuously
6386 Re-clock the last clocked task. With one {{{kbd(C-u)}}} prefix
6387 argument, select the task from the clock history. With two
6388 {{{kbd(C-u)}}} prefixes, force continuous clocking by starting the
6389 clock when the last clock stopped.
6391 - {{{kbd(C-c C-x C-e)}}} (~org-clock-modify-effort-estimate~) ::
6393 #+kindex: C-c C-x C-e
6394 #+findex: org-clock-modify-effort-estimate
6395 Update the effort estimate for the current clock task.
6397 - {{{kbd(C-c C-c)}}} or {{{kbd(C-c C-y)}}} (~org-evaluate-time-range~) ::
6401 #+findex: org-evaluate-time-range
6402 Recompute the time interval after changing one of the timestamps.
6403 This is only necessary if you edit the timestamps directly. If you
6404 change them with {{{kbd(S-<cursor>)}}} keys, the update is
6407 - {{{kbd(C-S-UP)}}} (~org-clock-timestamps-up~), {{{kbd(C-S-DOWN)}}} (~org-clock-timestamps-down~) ::
6410 #+findex: org-clock-timestamps-up
6412 #+findex: org-clock-timestamps-down
6413 On CLOCK log lines, increase/decrease both timestamps so that the
6414 clock duration keeps the same value.
6416 - {{{kbd(S-M-UP)}}} (~org-timestamp-up~), {{{kbd(S-M-DOWN)}}} (~org-timestamp-down~) ::
6419 #+findex: org-clock-timestamp-up
6421 #+findex: org-clock-timestamp-down
6422 On =CLOCK= log lines, increase/decrease the timestamp at point and
6423 the one of the previous, or the next, clock timestamp by the same
6424 duration. For example, if you hit {{{kbd(S-M-UP)}}} to increase
6425 a clocked-out timestamp by five minutes, then the clocked-in
6426 timestamp of the next clock is increased by five minutes.
6428 - {{{kbd(C-c C-t)}}} (~org-todo~) ::
6432 Changing the TODO state of an item to DONE automatically stops the
6433 clock if it is running in this same item.
6435 - {{{kbd(C-c C-x C-q)}}} (~org-clock-cancel~) ::
6437 #+kindex: C-c C-x C-q
6438 #+findex: org-clock-cancel
6439 Cancel the current clock. This is useful if a clock was started by
6440 mistake, or if you ended up working on something else.
6442 - {{{kbd(C-c C-x C-j)}}} (~org-clock-goto~) ::
6444 #+kindex: C-c C-x C-j
6445 #+findex: or-clock-goto
6446 Jump to the headline of the currently clocked in task. With
6447 a {{{kbd(C-u)}}} prefix argument, select the target task from a list
6448 of recently clocked tasks.
6450 - {{{kbd(C-c C-x C-d)}}} (~org-clock-display~) ::
6452 #+kindex: C-c C-x C-d
6453 #+findex: org-clock-display
6454 #+vindex: org-remove-highlights-with-change
6455 Display time summaries for each subtree in the current buffer. This
6456 puts overlays at the end of each headline, showing the total time
6457 recorded under that heading, including the time of any subheadings.
6458 You can use visibility cycling to study the tree, but the overlays
6459 disappear when you change the buffer (see variable
6460 ~org-remove-highlights-with-change~) or press {{{kbd(C-c C-c)}}}.
6462 The {{{kbd(l)}}} key may be used in the agenda (see [[*Weekly/daily
6463 agenda]]) to show which tasks have been worked on or closed during
6466 *Important:* note that both ~org-clock-out~ and ~org-clock-in-last~
6467 can have a global keybinding and do not modify the window disposition.
6471 :DESCRIPTION: Detailed reports.
6473 #+cindex: clocktable, dynamic block
6474 #+cindex: report, of clocked time
6476 Org mode can produce quite complex reports based on the time clocking
6477 information. Such a report is called a /clock table/, because it is
6478 formatted as one or several Org tables.
6480 You can insert, or update, a clock table through Org dynamic blocks
6481 insert command (see [[*Dynamic Blocks]]), by pressing {{{kbd(C-c C-x
6482 x c l o c k t a b l e RET)}}}. When called with a prefix argument,
6483 jump to the first clock table in the current document and update it.
6484 The clock table includes archived trees.
6486 #+attr_texinfo: :sep ,
6487 - {{{kbd(C-c C-c)}}} or {{{kbd(C-c C-x C-u)}}} (~org-dblock-update~) ::
6490 #+kindex: C-c C-x C-u
6491 #+findex: org-dblock-update
6492 Update dynamic block at point. Point needs to be in the =BEGIN=
6493 line of the dynamic block.
6495 - {{{kbd(C-u C-c C-x C-u)}}} ::
6497 #+kindex: C-u C-c C-x C-u
6498 Update all dynamic blocks (see [[*Dynamic Blocks]]). This is useful if
6499 you have several clock table blocks in a buffer.
6501 - {{{kbd(S-LEFT)}}}, {{{kbd(S-RIGHT)}}} (~org-clocktable-try-shift~) ::
6505 #+findex: org-clocktable-try-shift
6506 Shift the current =:block= interval and update the table. Point
6507 needs to be in the =#+BEGIN: clocktable= line for this command. If
6508 =:block= is =today=, it is shifted to =today-1=, etc.
6510 Here is an example of the frame for a clock table as it is inserted
6511 into the buffer with the {{{kbd(C-c C-x C-r)}}} command:
6513 #+cindex: @samp{BEGIN clocktable}
6515 ,#+BEGIN: clocktable :maxlevel 2 :emphasize nil :scope file
6519 #+vindex: org-clocktable-defaults
6520 The =#+BEGIN= line and specify a number of options to define the
6521 scope, structure, and formatting of the report. Defaults for all
6522 these options can be configured in the variable
6523 ~org-clocktable-defaults~.
6525 First there are options that determine which clock entries are to
6530 Maximum level depth to which times are listed in the table. Clocks
6531 at deeper levels are summed into the upper level.
6535 The scope to consider. This can be any of the following:
6537 | =nil= | the current buffer or narrowed region |
6538 | =file= | the full current buffer |
6539 | =subtree= | the subtree where the clocktable is located |
6540 | =treeN= | the surrounding level N tree, for example =tree3= |
6541 | =tree= | the surrounding level 1 tree |
6542 | =agenda= | all agenda files |
6543 | =("file" ...)= | scan these files |
6544 | =FUNCTION= | scan files returned by calling {{{var(FUNCTION)}}} with no argument |
6545 | =file-with-archives= | current file and its archives |
6546 | =agenda-with-archives= | all agenda files, including archives |
6550 The time block to consider. This block is specified either
6551 absolutely, or relative to the current time and may be any of these
6554 | =2007-12-31= | New year eve 2007 |
6555 | =2007-12= | December 2007 |
6556 | =2007-W50= | ISO-week 50 in 2007 |
6557 | =2007-Q2= | 2nd quarter in 2007 |
6558 | =2007= | the year 2007 |
6559 | =today=, =yesterday=, =today-N= | a relative day |
6560 | =thisweek=, =lastweek=, =thisweek-N= | a relative week |
6561 | =thismonth=, =lastmonth=, =thismonth-N= | a relative month |
6562 | =thisyear=, =lastyear=, =thisyear-N= | a relative year |
6563 | =untilnow=[fn:79] | all clocked time ever |
6565 #+vindex: org-clock-display-default-range
6566 When this option is not set, Org falls back to the value in
6567 ~org-clock-display-default-range~, which defaults to the current
6570 Use {{{kbd(S-LEFT)}}} or {{{kbd(S-RIGHT)}}} to shift the time
6575 A time string specifying when to start considering times. Relative
6576 times like ="<-2w>"= can also be used. See [[*Matching tags and
6577 properties]] for relative time syntax.
6581 A time string specifying when to stop considering times. Relative
6582 times like ="<now>"= can also be used. See [[*Matching tags and
6583 properties]] for relative time syntax.
6587 The starting day of the week. The default is 1 for Monday.
6591 The starting day of the month. The default is 1 for the first.
6595 Set to =day=, =week=, =month= or =year= to split the table into
6596 chunks. To use this, either =:block=, or =:tstart= and =:tend= are
6601 Do not show steps that have zero time.
6605 Do not show table sections from files which did not contribute.
6609 A tags match to select entries that should contribute. See
6610 [[*Matching tags and properties]] for the match syntax.
6612 #+findex: org-clocktable-write-default
6613 Then there are options that determine the formatting of the table.
6614 There options are interpreted by the function
6615 ~org-clocktable-write-default~, but you can specify your own function
6616 using the =:formatter= parameter.
6620 When ~t~, emphasize level one and level two items.
6624 Language[fn:80] to use for descriptive cells like "Task".
6628 Link the item headlines in the table to their origins.
6632 An integer to limit the width of the headline column in the Org
6633 table. If you write it like =50!=, then the headline is also
6634 shortened in export.
6638 Indent each headline field according to its level.
6642 Number of columns to be used for times. If this is smaller than
6643 =:maxlevel=, lower levels are lumped into one column.
6647 Should a level number column be included?
6651 A cons cell containing the column to sort and a sorting type. E.g.,
6652 =:sort (1 . ?a)= sorts the first column alphabetically.
6656 Abbreviation for =:level nil :indent t :narrow 40! :tcolumns 1=.
6657 All are overwritten except if there is an explicit =:narrow=.
6661 A timestamp for the entry, when available. Look for =SCHEDULED=,
6662 =DEADLINE=, =TIMESTAMP= and =TIMESTAMP_IA= special properties (see
6663 [[*Special Properties]]), in this order.
6667 When this flag is non-~nil~, show the headline's tags.
6671 List of properties shown in the table. Each property gets its own
6674 - =:inherit-props= ::
6676 When this flag is non-~nil~, the values for =:properties= are
6681 Content of a =TBLFM= keyword to be added and evaluated. As
6682 a special case, =:formula %= adds a column with % time. If you do
6683 not specify a formula here, any existing formula below the clock
6684 table survives updates and is evaluated.
6688 A function to format clock data and insert it into the buffer.
6690 To get a clock summary of the current level 1 tree, for the current
6691 day, you could write:
6694 ,#+BEGIN: clocktable :maxlevel 2 :block today :scope tree1 :link t
6698 #+texinfo: @noindent
6699 To use a specific time range you could write[fn:81]
6702 ,#+BEGIN: clocktable :tstart "<2006-08-10 Thu 10:00>"
6703 :tend "<2006-08-10 Thu 12:00>"
6707 #+texinfo: @noindent
6708 A range starting a week ago and ending right now could be written as
6711 ,#+BEGIN: clocktable :tstart "<-1w>" :tend "<now>"
6715 #+texinfo: @noindent
6716 A summary of the current subtree with % times would be
6719 ,#+BEGIN: clocktable :scope subtree :link t :formula %
6723 #+texinfo: @noindent
6724 A horizontally compact representation of everything clocked during
6728 ,#+BEGIN: clocktable :scope agenda :block lastweek :compact t
6732 *** Resolving idle time and continuous clocking
6734 :DESCRIPTION: Resolving time when you've been idle.
6735 :ALT_TITLE: Resolving idle time
6738 **** Resolving idle time
6743 #+cindex: resolve idle time
6744 #+cindex: idle, resolve, dangling
6746 If you clock in on a work item, and then walk away from your
6747 computer---perhaps to take a phone call---you often need to
6748 "resolve" the time you were away by either subtracting it from the
6749 current clock, or applying it to another one.
6751 #+vindex: org-clock-idle-time
6752 #+vindex: org-clock-x11idle-program-name
6753 By customizing the variable ~org-clock-idle-time~ to some integer,
6754 such as 10 or 15, Emacs can alert you when you get back to your
6755 computer after being idle for that many minutes[fn:82], and ask what
6756 you want to do with the idle time. There will be a question waiting
6757 for you when you get back, indicating how much idle time has passed
6758 constantly updated with the current amount, as well as a set of
6759 choices to correct the discrepancy:
6764 To keep some or all of the minutes and stay clocked in, press
6765 {{{kbd(k)}}}. Org asks how many of the minutes to keep. Press
6766 {{{kbd(RET)}}} to keep them all, effectively changing nothing, or
6767 enter a number to keep that many minutes.
6772 If you use the shift key and press {{{kbd(K)}}}, it keeps however
6773 many minutes you request and then immediately clock out of that
6774 task. If you keep all of the minutes, this is the same as just
6775 clocking out of the current task.
6780 To keep none of the minutes, use {{{kbd(s)}}} to subtract all the
6781 away time from the clock, and then check back in from the moment you
6787 To keep none of the minutes and just clock out at the start of the
6788 away time, use the shift key and press {{{kbd(S)}}}. Remember that
6789 using shift always leave you clocked out, no matter which option you
6795 To cancel the clock altogether, use {{{kbd(C)}}}. Note that if
6796 instead of canceling you subtract the away time, and the resulting
6797 clock amount is less than a minute, the clock is still canceled
6798 rather than cluttering up the log with an empty entry.
6800 What if you subtracted those away minutes from the current clock, and
6801 now want to apply them to a new clock? Simply clock in to any task
6802 immediately after the subtraction. Org will notice that you have
6803 subtracted time "on the books", so to speak, and will ask if you want
6804 to apply those minutes to the next task you clock in on.
6806 There is one other instance when this clock resolution magic occurs.
6807 Say you were clocked in and hacking away, and suddenly your cat chased
6808 a mouse who scared a hamster that crashed into your UPS's power
6809 button! You suddenly lose all your buffers, but thanks to auto-save
6810 you still have your recent Org mode changes, including your last clock
6813 If you restart Emacs and clock into any task, Org will notice that you
6814 have a dangling clock which was never clocked out from your last
6815 session. Using that clock's starting time as the beginning of the
6816 unaccounted-for period, Org will ask how you want to resolve that
6817 time. The logic and behavior is identical to dealing with away time
6818 due to idleness; it is just happening due to a recovery event rather
6819 than a set amount of idle time.
6821 You can also check all the files visited by your Org agenda for
6822 dangling clocks at any time using {{{kbd(M-x org-resolve-clocks
6823 RET)}}} (or {{{kbd(C-c C-x C-z)}}}).
6825 **** Continuous clocking
6829 #+cindex: continuous clocking
6831 #+vindex: org-clock-continuously
6832 You may want to start clocking from the time when you clocked out the
6833 previous task. To enable this systematically, set
6834 ~org-clock-continuously~ to non-~nil~. Each time you clock in, Org
6835 retrieves the clock-out time of the last clocked entry for this
6836 session, and start the new clock from there.
6838 If you only want this from time to time, use three universal prefix
6839 arguments with ~org-clock-in~ and two {{{kbd(C-u C-u)}}} with
6840 ~org-clock-in-last~.
6844 :DESCRIPTION: Planning work effort in advance.
6846 #+cindex: effort estimates
6847 #+cindex: @samp{EFFORT}, property
6848 #+vindex: org-effort-property
6850 If you want to plan your work in a very detailed way, or if you need
6851 to produce offers with quotations of the estimated work effort, you
6852 may want to assign effort estimates to entries. If you are also
6853 clocking your work, you may later want to compare the planned effort
6854 with the actual working time, a great way to improve planning
6855 estimates. Effort estimates are stored in a special property
6856 =EFFORT=. You can set the effort for an entry with the following
6859 - {{{kbd(C-c C-x e)}}} (~org-set-effort~) ::
6862 #+findex: org-set-effort
6863 Set the effort estimate for the current entry. With a prefix
6864 argument, set it to the next allowed value---see below. This
6865 command is also accessible from the agenda with the {{{kbd(e)}}}
6868 - {{{kbd(C-c C-x C-e)}}} (~org-clock-modify-effort-estimate~) ::
6870 #+kindex: C-c C-x C-e
6871 #+findex: org-clock-modify-effort-estimate
6872 Modify the effort estimate of the item currently being clocked.
6874 Clearly the best way to work with effort estimates is through column
6875 view (see [[*Column View]]). You should start by setting up discrete
6876 values for effort estimates, and a =COLUMNS= format that displays
6877 these values together with clock sums---if you want to clock your
6878 time. For a specific buffer you can use:
6881 ,#+PROPERTY: Effort_ALL 0 0:10 0:30 1:00 2:00 3:00 4:00 5:00 6:00 7:00
6882 ,#+COLUMNS: %40ITEM(Task) %17Effort(Estimated Effort){:} %CLOCKSUM
6885 #+texinfo: @noindent
6886 #+vindex: org-global-properties
6887 #+vindex: org-columns-default-format
6888 or, even better, you can set up these values globally by customizing
6889 the variables ~org-global-properties~ and
6890 ~org-columns-default-format~. In particular if you want to use this
6891 setup also in the agenda, a global setup may be advised.
6893 The way to assign estimates to individual items is then to switch to
6894 column mode, and to use {{{kbd(S-RIGHT)}}} and {{{kbd(S-LEFT)}}} to
6895 change the value. The values you enter are immediately summed up in
6896 the hierarchy. In the column next to it, any clocked time is
6899 #+vindex: org-agenda-columns-add-appointments-to-effort-sum
6900 If you switch to column view in the daily/weekly agenda, the effort
6901 column summarizes the estimated work effort for each day[fn:83], and
6902 you can use this to find space in your schedule. To get an overview
6903 of the entire part of the day that is committed, you can set the
6904 option ~org-agenda-columns-add-appointments-to-effort-sum~. The
6905 appointments on a day that take place over a specified time interval
6906 are then also added to the load estimate of the day.
6908 Effort estimates can be used in secondary agenda filtering that is
6909 triggered with the {{{kbd(/)}}} key in the agenda (see [[*Commands in
6910 the Agenda Buffer]]). If you have these estimates defined consistently,
6911 two or three key presses narrow down the list to stuff that fits into
6912 an available time slot.
6914 ** Taking Notes with a Relative Timer
6916 :DESCRIPTION: Notes with a running timer.
6919 #+cindex: relative timer
6920 #+cindex: countdown timer
6922 Org provides two types of timers. There is a relative timer that
6923 counts up, which can be useful when taking notes during, for example,
6924 a meeting or a video viewing. There is also a countdown timer.
6926 The relative and countdown are started with separate commands.
6928 - {{{kbd(C-c C-x 0)}}} (~org-timer-start~) ::
6931 #+findex: org-timer-start
6932 Start or reset the relative timer. By default, the timer is set
6933 to 0. When called with a {{{kbd(C-u)}}} prefix, prompt the user for
6934 a starting offset. If there is a timer string at point, this is
6935 taken as the default, providing a convenient way to restart taking
6936 notes after a break in the process. When called with a double
6937 prefix argument {{{kbd(C-u C-u)}}}, change all timer strings in the
6938 active region by a certain amount. This can be used to fix timer
6939 strings if the timer was not started at exactly the right moment.
6941 - {{{kbd(C-c C-x ;)}}} (~org-timer-set-timer~) ::
6944 #+findex: org-timer-set-timer
6945 #+vindex: org-timer-default-timer
6946 Start a countdown timer. The user is prompted for a duration.
6947 ~org-timer-default-timer~ sets the default countdown value. Giving
6948 a numeric prefix argument overrides this default value. This
6949 command is available as {{{kbd(;)}}} in agenda buffers.
6951 Once started, relative and countdown timers are controlled with the
6954 - {{{kbd(C-c C-x .)}}} (~org-timer~) ::
6958 Insert a relative time into the buffer. The first time you use
6959 this, the timer starts. Using a prefix argument restarts it.
6961 - {{{kbd(C-c C-x -)}}} (~org-timer-item~) ::
6964 #+findex: org-timer-item
6965 Insert a description list item with the current relative time. With
6966 a prefix argument, first reset the timer to 0.
6968 - {{{kbd(M-RET)}}} (~org-insert-heading~) ::
6971 #+findex: org-insert-heading
6972 Once the timer list is started, you can also use {{{kbd(M-RET)}}} to
6973 insert new timer items.
6975 - {{{kbd(C-c C-x \,)}}} (~org-timer-pause-or-continue~) ::
6978 #+findex: org-timer-pause-or-continue
6979 Pause the timer, or continue it if it is already paused.
6981 - {{{kbd(C-c C-x _)}}} (~org-timer-stop~) ::
6984 #+findex: org-timer-stop
6985 Stop the timer. After this, you can only start a new timer, not
6986 continue the old one. This command also removes the timer from the
6989 * Capture, Refile, Archive
6991 :DESCRIPTION: The ins and outs for projects.
6995 An important part of any organization system is the ability to quickly
6996 capture new ideas and tasks, and to associate reference material with
6997 them. Org does this using a process called /capture/. It also can
6998 store files related to a task (/attachments/) in a special directory.
6999 Once in the system, tasks and projects need to be moved around.
7000 Moving completed project trees to an archive file keeps the system
7005 :DESCRIPTION: Capturing new stuff.
7009 Capture lets you quickly store notes with little interruption of your
7010 work flow. Org's method for capturing new items is heavily inspired
7011 by John Wiegley's excellent Remember package.
7013 *** Setting up capture
7015 :DESCRIPTION: Where notes will be stored.
7018 The following customization sets a default target file for notes.
7020 #+vindex: org-default-notes-file
7021 #+begin_src emacs-lisp
7022 (setq org-default-notes-file (concat org-directory "/notes.org"))
7025 You may also define a global key for capturing new material (see
7030 :DESCRIPTION: Commands to invoke and terminate capture.
7033 - {{{kbd(M-x org-capture)}}} (~org-capture~) ::
7035 #+findex: org-capture
7037 Display the capture templates menu. If you have templates defined
7038 (see [[*Capture templates]]), it offers these templates for selection or
7039 use a new Org outline node as the default template. It inserts the
7040 template into the target file and switch to an indirect buffer
7041 narrowed to this new node. You may then insert the information you
7044 - {{{kbd(C-c C-c)}}} (~org-capture-finalize~) ::
7046 #+kindex: C-c C-c @r{(Capture buffer)}
7047 #+findex: org-capture-finalize
7048 Once you have finished entering information into the capture buffer,
7049 {{{kbd(C-c C-c)}}} returns you to the window configuration before
7050 the capture process, so that you can resume your work without
7051 further distraction. When called with a prefix argument, finalize
7052 and then jump to the captured item.
7054 - {{{kbd(C-c C-w)}}} (~org-capture-refile~) ::
7056 #+kindex: C-c C-w @r{(Capture buffer)}
7057 #+findex: org-capture-refile
7058 Finalize the capture process by refiling the note to a different
7059 place (see [[*Refile and Copy]]). Please realize that this is a normal
7060 refiling command that will be executed---so point position at the
7061 moment you run this command is important. If you have inserted
7062 a tree with a parent and children, first move point back to the
7063 parent. Any prefix argument given to this command is passed on to
7064 the ~org-refile~ command.
7066 - {{{kbd(C-c C-k)}}} (~org-capture-kill~) ::
7068 #+kindex: C-c C-k @r{(Capture buffer)}
7069 #+findex: org-capture-kill
7070 Abort the capture process and return to the previous state.
7072 #+kindex: k c @r{(Agenda)}
7073 You can also call ~org-capture~ in a special way from the agenda,
7074 using the {{{kbd(k c)}}} key combination. With this access, any
7075 timestamps inserted by the selected capture template defaults to the
7076 date at point in the agenda, rather than to the current date.
7078 To find the locations of the last stored capture, use ~org-capture~
7079 with prefix commands:
7081 - {{{kbd(C-u M-x org-capture)}}} ::
7083 Visit the target location of a capture template. You get to select
7084 the template in the usual way.
7086 - {{{kbd(C-u C-u M-x org-capture)}}} ::
7088 Visit the last stored capture item in its buffer.
7090 #+vindex: org-capture-bookmark
7091 #+vindex: org-capture-last-stored
7092 You can also jump to the bookmark ~org-capture-last-stored~, which is
7093 automatically created unless you set ~org-capture-bookmark~ to ~nil~.
7095 To insert the capture at point in an Org buffer, call ~org-capture~
7096 with a {{{kbd(C-0)}}} prefix argument.
7098 *** Capture templates
7100 :DESCRIPTION: Define the outline of different note types.
7102 #+cindex: templates, for Capture
7104 You can use templates for different types of capture items, and for
7105 different target locations. The easiest way to create such templates
7106 is through the customize interface.
7110 #+kindex: C @r{(Capture menu}
7111 #+vindex: org-capture-templates
7112 Customize the variable ~org-capture-templates~.
7114 Before we give the formal description of template definitions, let's
7115 look at an example. Say you would like to use one template to create
7116 general TODO entries, and you want to put these entries under the
7117 heading =Tasks= in your file =~/org/gtd.org=. Also, a date tree in
7118 the file =journal.org= should capture journal entries. A possible
7119 configuration would look like:
7121 #+begin_src emacs-lisp
7122 (setq org-capture-templates
7123 '(("t" "Todo" entry (file+headline "~/org/gtd.org" "Tasks")
7124 "* TODO %?\n %i\n %a")
7125 ("j" "Journal" entry (file+datetree "~/org/journal.org")
7126 "* %?\nEntered on %U\n %i\n %a")))
7129 #+texinfo: @noindent
7130 If you then press {{{kbd(t)}}} from the capture menu, Org will prepare
7131 the template for you like this:
7135 [[file:LINK TO WHERE YOU INITIATED CAPTURE]]
7138 #+texinfo: @noindent
7139 During expansion of the template, =%a= has been replaced by a link to
7140 the location from where you called the capture command. This can be
7141 extremely useful for deriving tasks from emails, for example. You
7142 fill in the task definition, press {{{kbd(C-c C-c)}}} and Org returns
7143 you to the same place where you started the capture process.
7145 To define special keys to capture to a particular template without
7146 going through the interactive template selection, you can create your
7147 key binding like this:
7149 #+begin_src emacs-lisp
7150 (define-key global-map "\C-cx"
7151 (lambda () (interactive) (org-capture nil "x")))
7154 **** Template elements
7156 :DESCRIPTION: What is needed for a complete template entry.
7159 Now lets look at the elements of a template definition. Each entry in
7160 ~org-capture-templates~ is a list with the following items:
7164 The keys that selects the template, as a string, characters only,
7165 for example ="a"=, for a template to be selected with a single key,
7166 or ="bt"= for selection with two keys. When using several keys,
7167 keys using the same prefix key must be sequential in the list and
7168 preceded by a 2-element entry explaining the prefix key, for
7171 #+begin_src emacs-lisp
7172 ("b" "Templates for marking stuff to buy")
7175 If you do not define a template for the {{{kbd(C)}}} key, this key
7176 opens the Customize buffer for this complex variable.
7180 A short string describing the template, shown during selection.
7184 The type of entry, a symbol. Valid values are:
7188 An Org mode node, with a headline. Will be filed as the child of
7189 the target entry or as a top-level entry. The target file should
7194 A plain list item, placed in the first plain list at the target
7195 location. Again the target file should be an Org file.
7199 A checkbox item. This only differs from the plain list item by
7200 the default template.
7204 A new line in the first table at the target location. Where
7205 exactly the line will be inserted depends on the properties
7206 ~:prepend~ and ~:table-line-pos~ (see below).
7210 Text to be inserted as it is.
7214 #+vindex: org-default-notes-file
7215 #+vindex: org-directory
7216 Specification of where the captured item should be placed. In Org
7217 files, targets usually define a node. Entries will become children
7218 of this node. Other types will be added to the table or list in the
7219 body of this node. Most target specifications contain a file name.
7220 If that file name is the empty string, it defaults to
7221 ~org-default-notes-file~. A file can also be given as a variable or
7222 as a function called with no argument. When an absolute path is not
7223 specified for a target, it is taken as relative to ~org-directory~.
7227 - =(file "path/to/file")= ::
7229 Text will be placed at the beginning or end of that file.
7231 - =(id "id of existing org entry")= ::
7233 Filing as child of this entry, or in the body of the entry.
7235 - =(file+headline "filename" "node headline")= ::
7237 Fast configuration if the target heading is unique in the file.
7239 - =(file+olp "filename" "Level 1 heading" "Level 2" ...)= ::
7241 For non-unique headings, the full path is safer.
7243 - =(file+regexp "filename" "regexp to find location")= ::
7245 Use a regular expression to position point.
7247 - =(file+olp+datetree "filename" [ "Level 1 heading" ...])= ::
7249 This target[fn:84] creates a heading in a date tree[fn:85] for
7250 today's date. If the optional outline path is given, the tree
7251 will be built under the node it is pointing to, instead of at top
7252 level. Check out the ~:time-prompt~ and ~:tree-type~ properties
7253 below for additional options.
7255 - =(file+function "filename" function-finding-location)= ::
7257 A function to find the right location in the file.
7261 File to the entry that is currently being clocked.
7263 - =(function function-finding-location)= ::
7265 Most general way: write your own function which both visits the
7266 file and moves point to the right location.
7270 The template for creating the capture item. If you leave this
7271 empty, an appropriate default template will be used. Otherwise this
7272 is a string with escape codes, which will be replaced depending on
7273 time and context of the capture call. The string with escapes may
7274 be loaded from a template file, using the special syntax =(file
7275 "template filename")=. See below for more details.
7279 The rest of the entry is a property list of additional options.
7280 Recognized properties are:
7284 Normally new captured information will be appended at the target
7285 location (last child, last table line, last list item, ...).
7286 Setting this property changes that.
7288 - ~:immediate-finish~ ::
7290 When set, do not offer to edit the information, just file it away
7291 immediately. This makes sense if the template only needs
7292 information that can be added automatically.
7296 Set this to the number of lines to insert before and after the new
7297 item. Default 0, and the only other common value is 1.
7301 Start the clock in this item.
7305 Keep the clock running when filing the captured entry.
7307 - ~:clock-resume~ ::
7309 If starting the capture interrupted a clock, restart that clock
7310 when finished with the capture. Note that ~:clock-keep~ has
7311 precedence over ~:clock-resume~. When setting both to non-~nil~,
7312 the current clock will run and the previous one will not be
7317 Prompt for a date/time to be used for date/week trees and when
7318 filling the template. Without this property, capture uses the
7319 current date and time. Even if this property has not been set,
7320 you can force the same behavior by calling ~org-capture~ with
7321 a {{{kbd(C-1)}}} prefix argument.
7325 When ~week~, make a week tree instead of the month tree, i.e.,
7326 place the headings for each day under a heading with the current
7331 Do not narrow the target buffer, simply show the full buffer.
7332 Default is to narrow it so that you only see the new material.
7334 - ~:table-line-pos~ ::
7336 Specification of the location in the table where the new line
7337 should be inserted. It should be a string like =II-3= meaning
7338 that the new line should become the third line before the second
7339 horizontal separator line.
7343 If the target file was not yet visited when capture was invoked,
7344 kill the buffer again after capture is completed.
7348 Do not save the target file after finishing the capture.
7350 **** Template expansion
7352 :DESCRIPTION: Filling in information about time and context.
7355 In the template itself, special "%-escapes"[fn:86] allow dynamic
7356 insertion of content. The templates are expanded in the order given
7361 Insert the contents of the file given by {{{var(FILE)}}}.
7365 Evaluate Elisp expression {{{var(EXP)}}} and replace it with the
7366 result. The {{{var(EXP)}}} form must return a string. Only
7367 placeholders pre-existing within the template, or introduced with
7368 =%[file]=, are expanded this way. Since this happens after
7369 expanding non-interactive "%-escapes", those can be used to fill the
7374 The result of format-time-string on the {{{var(FORMAT)}}}
7379 Timestamp, date only.
7383 Timestamp, with date and time.
7387 Like =%t=, =%T= above, but inactive timestamps.
7391 Initial content, the region when capture is called while the region
7392 is active. If there is text before =%i= on the same line, such as
7393 indentation, and =%i= is not inside a =%(exp)= form, that prefix is
7394 added before every line in the inserted text.
7398 Annotation, normally the link created with ~org-store-link~.
7402 Like =%a=, but prompt for the description part.
7406 Like =%a=, but only insert the literal link.
7410 Current kill ring head.
7414 Content of the X clipboard.
7418 Title of the currently clocked task.
7422 Link to the currently clocked task.
7426 User name (taken from ~user-full-name~).
7430 File visited by current buffer when org-capture was called.
7434 Full path of the file or directory visited by current buffer.
7438 Specific information for certain link types, see below.
7442 Prompt for tags, with completion on tags in target file.
7446 Prompt for tags, with completion all tags in all agenda files.
7450 Like =%t=, but prompt for date. Similarly =%^T=, =%^u=, =%^U=. You
7451 may define a prompt like =%^{Birthday}t=.
7455 Interactive selection of which kill or clip to use.
7459 Like =%^C=, but insert as link.
7463 Prompt the user for a value for property {{{var(PROP)}}}.
7467 Prompt the user for a string and replace this sequence with it. You
7468 may specify a default value and a completion table with
7469 =%^{prompt|default|completion2|completion3...}=. The arrow keys
7470 access a prompt-specific history.
7474 Insert the text entered at the {{{var(N)}}}th =%^{PROMPT}=, where
7475 {{{var(N)}}} is a number, starting from 1.
7479 After completing the template, position point here.
7481 #+vindex: org-store-link-props
7482 For specific link types, the following keywords are defined[fn:87]:
7484 #+vindex: org-from-is-user-regexp
7485 | Link type | Available keywords |
7486 |--------------+----------------------------------------------------------|
7487 | bbdb | =%:name=, =%:company= |
7488 | irc | =%:server=, =%:port=, =%:nick= |
7489 | mh, rmail | =%:type=, =%:subject=, =%:message-id= |
7490 | | =%:from=, =%:fromname=, =%:fromaddress= |
7491 | | =%:to=, =%:toname=, =%:toaddress= |
7492 | | =%:date= (message date header field) |
7493 | | =%:date-timestamp= (date as active timestamp) |
7494 | | =%:date-timestamp-inactive= (date as inactive timestamp) |
7495 | | =%:fromto= (either "to NAME" or "from NAME")[fn:88] |
7496 | gnus | =%:group=, for messages also all email fields |
7497 | w3, w3m | =%:url= |
7498 | info | =%:file=, =%:node= |
7499 | calendar | =%:date= |
7500 | org-protocol | =%:link=, =%:description=, =%:annotation= |
7502 **** Templates in contexts
7504 :DESCRIPTION: Only show a template in a specific context.
7507 #+vindex: org-capture-templates-contexts
7508 To control whether a capture template should be accessible from
7509 a specific context, you can customize
7510 ~org-capture-templates-contexts~. Let's say, for example, that you
7511 have a capture template "p" for storing Gnus emails containing
7512 patches. Then you would configure this option like this:
7514 #+begin_src emacs-lisp
7515 (setq org-capture-templates-contexts
7516 '(("p" (in-mode . "message-mode"))))
7519 You can also tell that the command key {{{kbd(p)}}} should refer to
7520 another template. In that case, add this command key like this:
7522 #+begin_src emacs-lisp
7523 (setq org-capture-templates-contexts
7524 '(("p" "q" (in-mode . "message-mode"))))
7527 See the docstring of the variable for more information.
7531 :DESCRIPTION: Add files to tasks.
7533 #+cindex: attachments
7534 #+vindex: org-attach-directory
7536 It is often useful to associate reference material with an outline
7537 node/task. Small chunks of plain text can simply be stored in the
7538 subtree of a project. Hyperlinks (see [[*Hyperlinks]]) can establish
7539 associations with files that live elsewhere on your computer or in the
7540 cloud, like emails or source code files belonging to a project.
7541 Another method is /attachments/, which are files located in
7542 a directory belonging to an outline node. Org uses directories named
7543 by the unique ID of each entry. These directories are located in the
7544 =data/= directory which lives in the same directory where your Org
7545 file lives[fn:89]. If you initialize this directory with =git init=,
7546 Org automatically commits changes when it sees them. The attachment
7547 system has been contributed to Org by John Wiegley.
7549 In cases where it seems better to do so, you can attach a directory of
7550 your choice to an entry. You can also make children inherit the
7551 attachment directory from a parent, so that an entire subtree uses the
7552 same attached directory.
7554 The following commands deal with attachments:
7556 - {{{kbd(C-c C-a)}}} (~org-attach~) ::
7559 #+findex: org-attach
7560 The dispatcher for commands related to the attachment system. After
7561 these keys, a list of commands is displayed and you must press an
7562 additional key to select a command:
7564 - {{{kbd(a)}}} (~org-attach-attach~) ::
7567 #+findex: org-attach-attach
7568 #+vindex: org-attach-method
7569 Select a file and move it into the task's attachment directory.
7570 The file is copied, moved, or linked, depending on
7571 ~org-attach-method~. Note that hard links are not supported on
7574 - {{{kbd(c)}}}/{{{kbd(m)}}}/{{{kbd(l)}}} ::
7579 Attach a file using the copy/move/link method. Note that hard
7580 links are not supported on all systems.
7582 - {{{kbd(b)}}} (~org-attach-buffer~) ::
7585 #+findex: org-attach-buffer
7586 Select a buffer and save it as a file in the task's attachment
7589 - {{{kbd(n)}}} (~org-attach-new~) ::
7592 #+findex: org-attach-new
7593 Create a new attachment as an Emacs buffer.
7595 - {{{kbd(z)}}} (~org-attach-sync~) ::
7598 #+findex: org-attach-sync
7599 Synchronize the current task with its attachment directory, in
7600 case you added attachments yourself.
7602 - {{{kbd(o)}}} (~org-attach-open~) ::
7605 #+findex: org-attach-open
7606 #+vindex: org-file-apps
7607 Open current task's attachment. If there is more than one, prompt
7608 for a file name first. Opening follows the rules set by
7609 ~org-file-apps~. For more details, see the information on
7610 following hyperlinks (see [[*Handling Links]]).
7612 - {{{kbd(O)}}} (~org-attach-open-in-emacs~) ::
7615 #+findex: org-attach-open-in-emacs
7616 Also open the attachment, but force opening the file in Emacs.
7618 - {{{kbd(f)}}} (~org-attach-reveal~) ::
7621 #+findex: org-attach-reveal
7622 Open the current task's attachment directory.
7624 - {{{kbd(F)}}} (~org-attach-reveal-in-emacs~) ::
7627 #+findex: org-attach-reveal-in-emacs
7628 Also open the directory, but force using Dired in Emacs.
7630 - {{{kbd(d)}}} (~org-attach-delete-one~) ::
7633 Select and delete a single attachment.
7635 - {{{kbd(D)}}} (~org-attach-delete-all~) ::
7638 Delete all of a task's attachments. A safer way is to open the
7639 directory in Dired and delete from there.
7641 - {{{kbd(s)}}} (~org-attach-set-directory~) ::
7644 #+cindex: @samp{ATTACH_DIR}, property
7645 Set a specific directory as the entry's attachment directory.
7646 This works by putting the directory path into the =ATTACH_DIR=
7649 - {{{kbd(i)}}} (~org-attach-set-inherit~) ::
7652 #+cindex: @samp{ATTACH_DIR_INHERIT}, property
7653 Set the =ATTACH_DIR_INHERIT= property, so that children use the
7654 same directory for attachments as the parent does.
7656 #+cindex: attach from Dired
7657 #+findex: org-attach-dired-to-subtree
7658 It is possible to attach files to a subtree from a Dired buffer. To
7659 use this feature, have one window in Dired mode containing the file(s)
7660 to be attached and another window with point in the subtree that shall
7661 get the attachments. In the Dired window, with point on a file,
7662 {{{kbd(M-x org-attach-dired-to-subtree)}}} attaches the file to the
7663 subtree using the attachment method set by variable
7664 ~org-attach-method~. When files are marked in the Dired window then
7665 all marked files get attached.
7667 Add the following lines to the Emacs init file to have {{{kbd(C-c C-x
7668 a)}}} attach files in Dired buffers.
7670 #+begin_src emacs-lisp
7671 (add-hook 'dired-mode-hook
7673 (define-key dired-mode-map
7675 #'org-attach-dired-to-subtree)))
7678 The following code shows how to bind the previous command with
7679 a specific attachment method.
7681 #+begin_src emacs-lisp
7682 (add-hook 'dired-mode-hook
7684 (define-key dired-mode-map (kbd "C-c C-x c")
7687 (let ((org-attach-method 'cp))
7688 (call-interactively #'org-attach-dired-to-subtree))))))
7693 :DESCRIPTION: Getting input from RSS feeds.
7696 #+cindex: Atom feeds
7698 Org can add and change entries based on information found in RSS feeds
7699 and Atom feeds. You could use this to make a task out of each new
7700 podcast in a podcast feed. Or you could use a phone-based
7701 note-creating service on the web to import tasks into Org. To access
7702 feeds, configure the variable ~org-feed-alist~. The docstring of this
7703 variable has detailed information. With the following
7705 #+begin_src emacs-lisp
7706 (setq org-feed-alist
7708 "http://rss.slashdot.org/Slashdot/slashdot"
7709 "~/txt/org/feeds.org" "Slashdot Entries")))
7712 #+texinfo: @noindent
7713 new items from the feed provided by =rss.slashdot.org= result in new
7714 entries in the file =~/org/feeds.org= under the heading =Slashdot
7715 Entries=, whenever the following command is used:
7717 - {{{kbd(C-c C-x g)}}} (~org-feed-update-all~) ::
7720 Collect items from the feeds configured in ~org-feed-alist~ and act
7723 - {{{kbd(C-c C-x G)}}} (~org-feed-goto-inbox~) ::
7726 Prompt for a feed name and go to the inbox configured for this feed.
7728 Under the same headline, Org creates a drawer =FEEDSTATUS= in which it
7729 stores information about the status of items in the feed, to avoid
7730 adding the same item several times.
7732 For more information, including how to read atom feeds, see
7733 =org-feed.el= and the docstring of ~org-feed-alist~.
7735 ** Protocols for External Access
7737 :DESCRIPTION: External access to Emacs and Org.
7738 :ALT_TITLE: Protocols
7740 #+cindex: protocols, for external access
7742 Org protocol is a means to trigger custom actions in Emacs from
7743 external applications. Any application that supports calling external
7744 programs with an URL as argument may be used with this functionality.
7745 For example, you can configure bookmarks in your web browser to send
7746 a link to the current page to Org and create a note from it using
7747 capture (see [[*Capture]]). You can also create a bookmark that tells
7748 Emacs to open the local source file of a remote website you are
7751 #+cindex: Org protocol, set-up
7752 #+cindex: Installing Org protocol
7753 In order to use Org protocol from an application, you need to register
7754 =org-protocol://= as a valid scheme-handler. External calls are
7755 passed to Emacs through the =emacsclient= command, so you also need to
7756 ensure an Emacs server is running. More precisely, when the
7759 : emacsclient org-protocol://PROTOCOL?key1=val1&key2=val2
7761 #+texinfo: @noindent
7762 Emacs calls the handler associated to {{{var(PROTOCOL)}}} with
7763 argument =(:key1 val1 :key2 val2)=.
7765 #+cindex: protocol, new protocol
7766 #+cindex: defining new protocols
7767 Org protocol comes with three predefined protocols, detailed in the
7768 following sections. Configure ~org-protocol-protocol-alist~ to define
7771 *** ~store-link~ protocol
7773 :DESCRIPTION: Store a link, push URL to kill-ring.
7775 #+cindex: store-link protocol
7776 #+cindex: protocol, store-link
7778 Using ~store-link~ handler, you can copy links, insertable through
7779 {{{kbd(M-x org-insert-link)}}} or yanking thereafter. More precisely,
7782 : emacsclient org-protocol://store-link?url=URL&title=TITLE
7784 #+texinfo: @noindent
7785 stores the following link:
7789 In addition, {{{var(URL)}}} is pushed on the kill-ring for yanking.
7790 You need to encode {{{var(URL)}}} and {{{var(TITLE)}}} if they contain
7791 slashes, and probably quote those for the shell.
7793 To use this feature from a browser, add a bookmark with an arbitrary
7794 name, e.g., =Org: store-link= and enter this as /Location/:
7797 javascript:location.href='org-protocol://store-link?url='+
7798 encodeURIComponent(location.href);
7801 *** ~capture~ protocol
7803 :DESCRIPTION: Fill a buffer with external information.
7805 #+cindex: capture protocol
7806 #+cindex: protocol, capture
7808 Activating "capture" handler pops up a =Capture= buffer and fills the
7809 capture template associated to the =X= key with them.
7811 : emacsclient org-protocol://capture?template=X?url=URL?title=TITLE?body=BODY
7813 To use this feature, add a bookmark with an arbitrary name, e.g.,
7814 =Org: capture=, and enter this as =Location=:
7817 javascript:location.href='org-protocol://capture?template=x'+
7818 '&url='+encodeURIComponent(window.location.href)+
7819 '&title='+encodeURIComponent(document.title)+
7820 '&body='+encodeURIComponent(window.getSelection());
7823 #+vindex: org-protocol-default-template-key
7824 The result depends on the capture template used, which is set in the
7825 bookmark itself, as in the example above, or in
7826 ~org-protocol-default-template-key~.
7828 The following template placeholders are available:
7832 %:description The webpage title
7833 %:annotation Equivalent to [[%:link][%:description]]
7834 %i The selected text
7837 *** ~open-source~ protocol
7839 :DESCRIPTION: Edit published contents.
7841 #+cindex: open-source protocol
7842 #+cindex: protocol, open-source
7844 The ~open-source~ handler is designed to help with editing local
7845 sources when reading a document. To that effect, you can use
7846 a bookmark with the following location:
7849 javascript:location.href='org-protocol://open-source?&url='+
7850 encodeURIComponent(location.href)
7853 #+vindex: org-protocol-project-alist
7854 The variable ~org-protocol-project-alist~ maps URLs to local file
7855 names, by stripping URL parameters from the end and replacing the
7856 ~:base-url~ with ~:working-directory~ and ~:online-suffix~ with
7857 ~:working-suffix~. For example, assuming you own a local copy of
7858 =https://orgmode.org/worg/= contents at =/home/user/worg=, you can set
7859 ~org-protocol-project-alist~ to the following
7861 #+begin_src emacs-lisp
7862 (setq org-protocol-project-alist
7864 :base-url "https://orgmode.org/worg/"
7865 :working-directory "/home/user/worg/"
7866 :online-suffix ".html"
7867 :working-suffix ".org")))
7870 #+texinfo: @noindent
7871 If you are now browsing
7872 =https://orgmode.org/worg/org-contrib/org-protocol.html= and find
7873 a typo or have an idea about how to enhance the documentation, simply
7874 click the bookmark and start editing.
7876 #+cindex: rewritten URL in open-source protocol
7877 #+cindex: protocol, open-source rewritten URL
7878 However, such mapping may not yield the desired results. Suppose you
7879 maintain an online store located at =http://example.com/=. The local
7880 sources reside in =/home/user/example/=. It is common practice to
7881 serve all products in such a store through one file and rewrite URLs
7882 that do not match an existing file on the server. That way, a request
7883 to =http://example.com/print/posters.html= might be rewritten on the
7884 server to something like
7885 =http://example.com/shop/products.php/posters.html.php=. The
7886 ~open-source~ handler probably cannot find a file named
7887 =/home/user/example/print/posters.html.php= and fails.
7889 Such an entry in ~org-protocol-project-alist~ may hold an additional
7890 property ~:rewrites~. This property is a list of cons cells, each of
7891 which maps a regular expression to a path relative to the
7892 ~:working-directory~.
7894 Now map the URL to the path =/home/user/example/products.php= by
7895 adding ~:rewrites~ rules like this:
7897 #+begin_src emacs-lisp
7898 (setq org-protocol-project-alist
7900 :base-url "http://example.com/"
7901 :working-directory "/home/user/example/"
7902 :online-suffix ".php"
7903 :working-suffix ".php"
7904 :rewrites (("example.com/print/" . "products.php")
7905 ("example.com/$" . "index.php")))))
7908 #+texinfo: @noindent
7909 Since =example.com/$= is used as a regular expression, it maps
7910 =http://example.com/=, =https://example.com=,
7911 =http://www.example.com/= and similar to
7912 =/home/user/example/index.php=.
7914 The ~:rewrites~ rules are searched as a last resort if and only if no
7915 existing file name is matched.
7917 #+cindex: protocol, open-source, set-up mapping
7918 #+cindex: mappings in open-source protocol
7919 #+findex: org-protocol-create
7920 #+findex: org-protocol-create-for-org
7921 Two functions can help you filling ~org-protocol-project-alist~ with
7922 valid contents: ~org-protocol-create~ and
7923 ~org-protocol-create-for-org~. The latter is of use if you're editing
7924 an Org file that is part of a publishing project.
7928 :DESCRIPTION: Moving/copying a tree from one place to another.
7930 #+cindex: refiling notes
7931 #+cindex: copying notes
7933 When reviewing the captured data, you may want to refile or to copy
7934 some of the entries into a different list, for example into a project.
7935 Cutting, finding the right location, and then pasting the note is
7936 cumbersome. To simplify this process, you can use the following
7939 - {{{kbd(C-c M-w)}}} (~org-copy~) ::
7943 Copying works like refiling, except that the original note is not
7946 - {{{kbd(C-c C-w)}}} (~org-refile~) ::
7949 #+findex: org-refile
7950 #+vindex: org-reverse-note-order
7951 #+vindex: org-refile-targets
7952 #+vindex: org-refile-use-outline-path
7953 #+vindex: org-outline-path-complete-in-steps
7954 #+vindex: org-refile-allow-creating-parent-nodes
7955 #+vindex: org-log-refile
7956 Refile the entry or region at point. This command offers possible
7957 locations for refiling the entry and lets you select one with
7958 completion. The item (or all items in the region) is filed below
7959 the target heading as a subitem. Depending on
7960 ~org-reverse-note-order~, it is either the first or last subitem.
7962 By default, all level 1 headlines in the current buffer are
7963 considered to be targets, but you can have more complex definitions
7964 across a number of files. See the variable ~org-refile-targets~ for
7965 details. If you would like to select a location via
7966 a file-path-like completion along the outline path, see the
7967 variables ~org-refile-use-outline-path~ and
7968 ~org-outline-path-complete-in-steps~. If you would like to be able
7969 to create new nodes as new parents for refiling on the fly, check
7970 the variable ~org-refile-allow-creating-parent-nodes~. When the
7971 variable ~org-log-refile~[fn:90] is set, a timestamp or a note is
7972 recorded whenever an entry is refiled.
7974 - {{{kbd(C-u C-c C-w)}}} ::
7976 #+kindex: C-u C-c C-w
7977 Use the refile interface to jump to a heading.
7979 - {{{kbd(C-u C-u C-c C-w)}}} (~org-refile-goto-last-stored~) ::
7981 #+kindex: C-u C-u C-c C-w
7982 #+findex: org-refile-goto-last-stored
7983 Jump to the location where ~org-refile~ last moved a tree to.
7985 - {{{kbd(C-2 C-c C-w)}}} ::
7987 #+kindex: C-2 C-c C-w
7988 Refile as the child of the item currently being clocked.
7990 - {{{kbd(C-3 C-c C-w)}}} ::
7992 #+kindex: C-3 C-c C-w
7993 #+vindex: org-refile-keep
7994 Refile and keep the entry in place. Also see ~org-refile-keep~ to
7995 make this the default behavior, and beware that this may result in
7996 duplicated =ID= properties.
7998 - {{{kbd(C-0 C-c C-w)}}} or {{{kbd(C-u C-u C-u C-c C-w)}}} (~org-refile-cache-clear~) ::
8000 #+kindex: C-u C-u C-u C-c C-w
8001 #+kindex: C-0 C-c C-w
8002 #+findex: org-refile-cache-clear
8003 #+vindex: org-refile-use-cache
8004 Clear the target cache. Caching of refile targets can be turned on
8005 by setting ~org-refile-use-cache~. To make the command see new
8006 possible targets, you have to clear the cache with this command.
8010 :DESCRIPTION: What to do with finished products.
8014 When a project represented by a (sub)tree is finished, you may want to
8015 move the tree out of the way and to stop it from contributing to the
8016 agenda. Archiving is important to keep your working files compact and
8017 global searches like the construction of agenda views fast.
8019 - {{{kbd(C-c C-x C-a)}}} (~org-archive-subtree-default~) ::
8021 #+kindex: C-c C-x C-a
8022 #+findex: org-archive-subtree-default
8023 #+vindex: org-archive-default-command
8024 Archive the current entry using the command specified in the
8025 variable ~org-archive-default-command~.
8027 *** Moving a tree to an archive file
8029 :DESCRIPTION: Moving a tree to an archive file.
8030 :ALT_TITLE: Moving subtrees
8032 #+cindex: external archiving
8034 The most common archiving action is to move a project tree to another
8035 file, the archive file.
8037 - {{{kbd(C-c C-x C-s)}}} or short {{{kbd(C-c $)}}} (~org-archive-subtree~) ::
8039 #+kindex: C-c C-x C-s
8041 #+findex: org-archive-subtree
8042 #+vindex: org-archive-location
8043 Archive the subtree starting at point position to the location given
8044 by ~org-archive-location~.
8046 - {{{kbd(C-u C-c C-x C-s)}}} ::
8048 #+kindex: C-u C-c C-x C-s
8049 Check if any direct children of the current headline could be moved
8050 to the archive. To do this, check each subtree for open TODO
8051 entries. If none is found, the command offers to move it to the
8052 archive location. If point is /not/ on a headline when this command
8053 is invoked, check level 1 trees.
8055 - {{{kbd(C-u C-u C-c C-x C-s)}}} ::
8057 #+kindex: C-u C-u C-c C-x C-s
8058 As above, but check subtree for timestamps instead of TODO entries.
8059 The command offers to archive the subtree if it /does/ contain
8060 a timestamp, and that timestamp is in the past.
8062 #+cindex: archive locations
8063 The default archive location is a file in the same directory as the
8064 current file, with the name derived by appending =_archive= to the
8065 current file name. You can also choose what heading to file archived
8066 items under, with the possibility to add them to a datetree in a file.
8067 For information and examples on how to specify the file and the
8068 heading, see the documentation string of the variable
8069 ~org-archive-location~.
8071 There is also an in-buffer option for setting this variable, for
8074 #+cindex: @samp{ARCHIVE}, keyword
8075 : #+ARCHIVE: %s_done::
8077 #+cindex: ARCHIVE, property
8078 If you would like to have a special archive location for a single
8079 entry or a (sub)tree, give the entry an =ARCHIVE= property with the
8080 location as the value (see [[*Properties and Columns]]).
8082 #+vindex: org-archive-save-context-info
8083 When a subtree is moved, it receives a number of special properties
8084 that record context information like the file from where the entry
8085 came, its outline path the archiving time etc. Configure the variable
8086 ~org-archive-save-context-info~ to adjust the amount of information
8089 *** Internal archiving
8091 :DESCRIPTION: Switch off a tree but keep it in the file.
8094 #+cindex: @samp{ARCHIVE}, tag
8095 If you want to just switch off---for agenda views---certain subtrees
8096 without moving them to a different file, you can use the =ARCHIVE=
8099 A headline that is marked with the =ARCHIVE= tag (see [[*Tags]]) stays at
8100 its location in the outline tree, but behaves in the following way:
8103 #+vindex: org-cycle-open-archived-trees
8104 It does not open when you attempt to do so with a visibility cycling
8105 command (see [[*Visibility Cycling]]). You can force cycling archived
8106 subtrees with {{{kbd(C-TAB)}}}, or by setting the option
8107 ~org-cycle-open-archived-trees~. Also normal outline commands, like
8108 ~outline-show-all~, open archived subtrees.
8111 #+vindex: org-sparse-tree-open-archived-trees
8112 During sparse tree construction (see [[*Sparse Trees]]), matches in
8113 archived subtrees are not exposed, unless you configure the option
8114 ~org-sparse-tree-open-archived-trees~.
8117 #+vindex: org-agenda-skip-archived-trees
8118 During agenda view construction (see [[*Agenda Views]]), the content of
8119 archived trees is ignored unless you configure the option
8120 ~org-agenda-skip-archived-trees~, in which case these trees are
8121 always included. In the agenda you can press {{{kbd(v a)}}} to get
8122 archives temporarily included.
8125 #+vindex: org-export-with-archived-trees
8126 Archived trees are not exported (see [[*Exporting]]), only the headline
8127 is. Configure the details using the variable
8128 ~org-export-with-archived-trees~.
8131 #+vindex: org-columns-skip-archived-trees
8132 Archived trees are excluded from column view unless the variable
8133 ~org-columns-skip-archived-trees~ is configured to ~nil~.
8135 The following commands help manage the =ARCHIVE= tag:
8137 - {{{kbd(C-c C-x a)}}} (~org-toggle-archive-tag~) ::
8140 #+findex: org-toggle-archive-tag
8141 Toggle the archive tag for the current headline. When the tag is
8142 set, the headline changes to a shadowed face, and the subtree below
8145 - {{{kbd(C-u C-c C-x a)}}} ::
8147 #+kindex: C-u C-c C-x a
8148 Check if any direct children of the current headline should be
8149 archived. To do this, check each subtree for open TODO entries. If
8150 none is found, the command offers to set the =ARCHIVE= tag for the
8151 child. If point is /not/ on a headline when this command is
8152 invoked, check the level 1 trees.
8154 - {{{kbd(C-TAB)}}} (~org-force-cycle-archived~) ::
8157 Cycle a tree even if it is tagged with =ARCHIVE=.
8159 - {{{kbd(C-c C-x A)}}} (~org-archive-to-archive-sibling~) ::
8162 #+findex: org-archive-to-archive-sibling
8163 Move the current entry to the /Archive Sibling/. This is a sibling
8164 of the entry with the heading =Archive= and the archive tag. The
8165 entry becomes a child of that sibling and in this way retains a lot
8166 of its original context, including inherited tags and approximate
8167 position in the outline.
8171 :DESCRIPTION: Collecting information into views.
8173 #+cindex: agenda views
8175 Due to the way Org works, TODO items, time-stamped items, and tagged
8176 headlines can be scattered throughout a file or even a number of
8177 files. To get an overview of open action items, or of events that are
8178 important for a particular date, this information must be collected,
8179 sorted and displayed in an organized way.
8181 Org can select items based on various criteria and display them in
8182 a separate buffer. Seven different view types are provided:
8184 - an /agenda/ that is like a calendar and shows information for
8187 - a /TODO list/ that covers all unfinished action items,
8189 - a /match view/, showings headlines based on the tags, properties,
8190 and TODO state associated with them,
8192 - a /text search view/ that shows all entries from multiple files that
8193 contain specified keywords,
8195 - a /stuck projects view/ showing projects that currently do not move
8198 - /custom views/ that are special searches and combinations of
8201 The extracted information is displayed in a special /agenda buffer/.
8202 This buffer is read-only, but provides commands to visit the
8203 corresponding locations in the original Org files, and even to edit
8204 these files remotely.
8206 #+vindex: org-agenda-skip-comment-trees
8207 #+vindex: org-agenda-skip-archived-trees
8208 #+cindex: commented entries, in agenda views
8209 #+cindex: archived entries, in agenda views
8210 By default, the report ignores commented (see [[*Comment Lines]]) and
8211 archived (see [[*Internal archiving]]) entries. You can override this by
8212 setting ~org-agenda-skip-comment-trees~ and
8213 ~org-agenda-skip-archived-trees~ to ~nil~.
8215 #+vindex: org-agenda-window-setup
8216 #+vindex: org-agenda-restore-windows-after-quit
8217 Two variables control how the agenda buffer is displayed and whether
8218 the window configuration is restored when the agenda exits:
8219 ~org-agenda-window-setup~ and ~org-agenda-restore-windows-after-quit~.
8223 :DESCRIPTION: Files being searched for agenda information.
8225 #+cindex: agenda files
8226 #+cindex: files for agenda
8228 #+vindex: org-agenda-files
8229 The information to be shown is normally collected from all /agenda
8230 files/, the files listed in the variable ~org-agenda-files~[fn:91].
8231 If a directory is part of this list, all files with the extension
8232 =.org= in this directory are part of the list.
8234 Thus, even if you only work with a single Org file, that file should
8235 be put into the list[fn:92]. You can customize ~org-agenda-files~,
8236 but the easiest way to maintain it is through the following commands
8238 #+attr_texinfo: :sep and
8239 - {{{kbd(C-c [)}}} (~org-agenda-file-to-front~) ::
8242 #+findex: org-agenda-file-to-front
8243 #+cindex: files, adding to agenda list
8244 Add current file to the list of agenda files. The file is added to
8245 the front of the list. If it was already in the list, it is moved
8246 to the front. With a prefix argument, file is added/moved to the
8249 - {{{kbd(C-c ])}}} (~org-remove-file~) ::
8252 #+findex: org-remove-file
8253 Remove current file from the list of agenda files.
8255 - {{{kbd(C-')}}} and {{{kbd(C-\,)}}} (~org-cycle-agenda-files~) ::
8259 #+findex: org-cycle-agenda-files
8260 #+cindex: cycling, of agenda files
8261 Cycle through agenda file list, visiting one file after the other.
8263 - {{{kbd(M-x org-switchb)}}} ::
8265 #+findex: org-switchb
8266 Command to use an iswitchb-like interface to switch to and between
8269 #+texinfo: @noindent
8270 The Org menu contains the current list of files and can be used to
8273 If you would like to focus the agenda temporarily on a file not in
8274 this list, or on just one file in the list, or even on only a subtree
8275 in a file, then this can be done in different ways. For a single
8276 agenda command, you may press {{{kbd(<)}}} once or several times in
8277 the dispatcher (see [[*The Agenda Dispatcher]]). To restrict the agenda
8278 scope for an extended period, use the following commands:
8280 - {{{kbd(C-c C-x <)}}} (~org-agenda-set-restriction-lock~) ::
8283 #+findex: org-agenda-set-restriction-lock
8284 Restrict the agenda to the current subtree. If there already is
8285 a restriction at point, remove it. When called with a universal
8286 prefix argument or with point before the first headline in a file,
8287 set the agenda scope to the entire file. This restriction remains
8288 in effect until removed with {{{kbd(C-c C-x >)}}}, or by typing
8289 either {{{kbd(<)}}} or {{{kbd(>)}}} in the agenda dispatcher. If
8290 there is a window displaying an agenda view, the new restriction
8291 takes effect immediately.
8293 - {{{kbd(C-c C-x >)}}} (~org-agenda-remove-restriction-lock~) ::
8296 #+findex: org-agenda-remove-restriction-lock
8297 Remove the restriction created by {{{kbd(C-c C-x <)}}}.
8299 When working with Speedbar, you can use the following commands in the
8302 - {{{kbd(<)}}} (~org-speedbar-set-agenda-restriction~) ::
8304 #+findex: org-speedbar-set-agenda-restriction
8305 Restrict the agenda to the item---either an Org file or a subtree in
8306 such a file---at point in the Speedbar frame. If agenda is already
8307 restricted there, remove the restriction. If there is a window
8308 displaying an agenda view, the new restriction takes effect
8311 - {{{kbd(>)}}} (~org-agenda-remove-restriction-lock~) ::
8313 #+findex: org-agenda-remove-restriction-lock
8314 Remove the restriction.
8316 ** The Agenda Dispatcher
8318 :DESCRIPTION: Keyboard access to agenda views.
8319 :ALT_TITLE: Agenda Dispatcher
8321 #+cindex: agenda dispatcher
8322 #+cindex: dispatching agenda commands
8324 The views are created through a dispatcher, accessible with {{{kbd(M-x
8325 org-agenda)}}}, or, better, bound to a global key (see [[*Activation]]).
8326 It displays a menu from which an additional letter is required to
8327 execute a command. The dispatcher offers the following default
8332 Create the calendar-like agenda (see [[*Weekly/daily agenda]]).
8334 - {{{kbd(t)}}} or {{{kbd(T)}}} ::
8336 Create a list of all TODO items (see [[*The global TODO list]]).
8338 - {{{kbd(m)}}} or {{{kbd(M)}}} ::
8340 Create a list of headlines matching a given expression (see
8341 [[*Matching tags and properties]]).
8345 #+kindex: s @r{(Agenda dispatcher)}
8346 Create a list of entries selected by a boolean expression of
8347 keywords and/or regular expressions that must or must not occur in
8352 #+kindex: / @r{(Agenda dispatcher)}
8353 #+vindex: org-agenda-text-search-extra-files
8354 Search for a regular expression in all agenda files and additionally
8355 in the files listed in ~org-agenda-text-search-extra-files~. This
8356 uses the Emacs command ~multi-occur~. A prefix argument can be used
8357 to specify the number of context lines for each match, default is
8360 - {{{kbd(#)}}} or {{{kbd(!)}}} ::
8362 Create a list of stuck projects (see [[*Stuck projects]]).
8366 #+kindex: < @r{(Agenda dispatcher)}
8367 Restrict an agenda command to the current buffer[fn:93]. After
8368 pressing {{{kbd(<)}}}, you still need to press the character
8369 selecting the command.
8373 #+kindex: < < @r{(Agenda dispatcher)}
8374 If there is an active region, restrict the following agenda command
8375 to the region. Otherwise, restrict it to the current
8376 subtree[fn:94]. After pressing {{{kbd(< <)}}}, you still need to
8377 press the character selecting the command.
8381 #+kindex: * @r{(Agenda dispatcher)}
8382 #+vindex: org-agenda-sticky
8383 #+findex: org-toggle-sticky-agenda
8384 Toggle sticky agenda views. By default, Org maintains only a single
8385 agenda buffer and rebuilds it each time you change the view, to make
8386 sure everything is always up to date. If you switch between views
8387 often and the build time bothers you, you can turn on sticky agenda
8388 buffers (make this the default by customizing the variable
8389 ~org-agenda-sticky~). With sticky agendas, the dispatcher only
8390 switches to the selected view, you need to update it by hand with
8391 {{{kbd(r)}}} or {{{kbd(g)}}}. You can toggle sticky agenda view any
8392 time with ~org-toggle-sticky-agenda~.
8394 You can also define custom commands that are accessible through the
8395 dispatcher, just like the default commands. This includes the
8396 possibility to create extended agenda buffers that contain several
8397 blocks together, for example the weekly agenda, the global TODO list
8398 and a number of special tags matches. See [[*Custom Agenda Views]].
8400 ** The Built-in Agenda Views
8402 :DESCRIPTION: What is available out of the box?
8403 :ALT_TITLE: Built-in Agenda Views
8406 In this section we describe the built-in views.
8408 *** Weekly/daily agenda
8410 :DESCRIPTION: The calendar page with current tasks.
8413 #+cindex: weekly agenda
8414 #+cindex: daily agenda
8416 The purpose of the weekly/daily /agenda/ is to act like a page of
8417 a paper agenda, showing all the tasks for the current week or day.
8419 - {{{kbd(M-x org-agenda a)}}} (~org-agenda-list~) ::
8421 #+kindex: a @r{(Agenda dispatcher)}
8422 #+findex: org-agenda-list
8423 #+cindex: org-agenda, command
8424 Compile an agenda for the current week from a list of Org files.
8425 The agenda shows the entries for each day. With a numeric prefix
8426 argument[fn:95]---like {{{kbd(C-u 2 1 M-x org-agenda a)}}}---you may
8427 set the number of days to be displayed.
8429 #+vindex: org-agenda-span
8430 #+vindex: org-agenda-start-day
8431 #+vindex: org-agenda-start-on-weekday
8432 The default number of days displayed in the agenda is set by the
8433 variable ~org-agenda-span~. This variable can be set to any number of
8434 days you want to see by default in the agenda, or to a span name, such
8435 a ~day~, ~week~, ~month~ or ~year~. For weekly agendas, the default
8436 is to start on the previous Monday (see
8437 ~org-agenda-start-on-weekday~). You can also set the start date using
8438 a date shift: =(setq org-agenda-start-day "+10d")= starts the agenda
8439 ten days from today in the future.
8441 Remote editing from the agenda buffer means, for example, that you can
8442 change the dates of deadlines and appointments from the agenda buffer.
8443 The commands available in the Agenda buffer are listed in [[*Commands in
8444 the Agenda Buffer]].
8446 **** Calendar/Diary integration
8450 #+cindex: calendar integration
8451 #+cindex: diary integration
8453 Emacs contains the calendar and diary by Edward\nbsp{}M.\nbsp{}Reingold. The
8454 calendar displays a three-month calendar with holidays from different
8455 countries and cultures. The diary allows you to keep track of
8456 anniversaries, lunar phases, sunrise/set, recurrent appointments
8457 (weekly, monthly) and more. In this way, it is quite complementary to
8458 Org. It can be very useful to combine output from Org with the diary.
8460 In order to include entries from the Emacs diary into Org mode's
8461 agenda, you only need to customize the variable
8463 #+begin_src emacs-lisp
8464 (setq org-agenda-include-diary t)
8467 #+texinfo: @noindent
8468 After that, everything happens automatically. All diary entries
8469 including holidays, anniversaries, etc., are included in the agenda
8470 buffer created by Org mode. {{{kbd(SPC)}}}, {{{kbd(TAB)}}}, and
8471 {{{kbd(RET)}}} can be used from the agenda buffer to jump to the diary
8472 file in order to edit existing diary entries. The {{{kbd(i)}}}
8473 command to insert new entries for the current date works in the agenda
8474 buffer, as well as the commands {{{kbd(S)}}}, {{{kbd(M)}}}, and
8475 {{{kbd(C)}}} to display Sunrise/Sunset times, show lunar phases and to
8476 convert to other calendars, respectively. {{{kbd(c)}}} can be used to
8477 switch back and forth between calendar and agenda.
8479 If you are using the diary only for S-exp entries and holidays, it is
8480 faster to not use the above setting, but instead to copy or even move
8481 the entries into an Org file. Org mode evaluates diary-style sexp
8482 entries, and does it faster because there is no overhead for first
8483 creating the diary display. Note that the sexp entries must start at
8484 the left margin, no whitespace is allowed before them, as seen in the
8485 following segment of an Org file:[fn:96]
8492 %%(org-calendar-holiday) ; special function for holiday names
8498 %%(org-anniversary 1956 5 14) Arthur Dent is %d years old
8499 %%(org-anniversary 1869 10 2) Mahatma Gandhi would be %d years old
8502 **** Anniversaries from BBDB
8506 #+cindex: BBDB, anniversaries
8507 #+cindex: anniversaries, from BBDB
8509 #+findex: org-bbdb-anniversaries
8510 If you are using the Insidious Big Brother Database to store your
8511 contacts, you very likely prefer to store anniversaries in BBDB rather
8512 than in a separate Org or diary file. Org supports this and can show
8513 BBDB anniversaries as part of the agenda. All you need to do is to
8514 add the following to one of your agenda files:
8521 %%(org-bbdb-anniversaries)
8524 You can then go ahead and define anniversaries for a BBDB record.
8525 Basically, you need a field named =anniversary= for the BBDB record
8526 which contains the date in the format =YYYY-MM-DD= or =MM-DD=,
8527 followed by a space and the class of the anniversary (=birthday=,
8528 =wedding=, or a format string). If you omit the class, it defaults to
8529 =birthday=. Here are a few examples, the header for the file
8530 =org-bbdb.el= contains more detailed information.
8536 2008-04-14 %s released version 6.01 of Org mode, %d years ago
8539 After a change to BBDB, or for the first agenda display during an
8540 Emacs session, the agenda display suffers a short delay as Org updates
8541 its hash with anniversaries. However, from then on things will be
8542 very fast, much faster in fact than a long list of
8543 =%%(diary-anniversary)= entries in an Org or Diary file.
8545 #+findex: org-bbdb-anniversaries-future
8546 If you would like to see upcoming anniversaries with a bit of
8547 forewarning, you can use the following instead:
8554 %%(org-bbdb-anniversaries-future 3)
8557 That will give you three days' warning: on the anniversary date itself
8558 and the two days prior. The argument is optional: if omitted, it
8561 **** Appointment reminders
8565 #+cindex: @file{appt.el}
8566 #+cindex: appointment reminders
8567 #+cindex: appointment
8570 #+cindex: APPT_WARNTIME, keyword
8571 Org can interact with Emacs appointments notification facility. To
8572 add the appointments of your agenda files, use the command
8573 ~org-agenda-to-appt~. This command lets you filter through the list
8574 of your appointments and add only those belonging to a specific
8575 category or matching a regular expression. It also reads
8576 a =APPT_WARNTIME= property which overrides the value of
8577 ~appt-message-warning-time~ for this appointment. See the docstring
8580 *** The global TODO list
8582 :DESCRIPTION: All unfinished action items.
8583 :ALT_TITLE: Global TODO list
8585 #+cindex: global TODO list
8586 #+cindex: TODO list, global
8588 The global TODO list contains all unfinished TODO items formatted and
8589 collected into a single place.
8591 - {{{kbd(M-x org-agenda t)}}} (~org-todo-list~) ::
8593 #+kindex: t @r{(Agenda dispatcher)}
8594 #+findex: org-todo-list
8595 Show the global TODO list. This collects the TODO items from all
8596 agenda files (see [[*Agenda Views]]) into a single buffer. By default,
8597 this lists items with a state the is not a DONE state. The buffer
8598 is in ~agenda-mode~, so there are commands to examine and manipulate
8599 the TODO entries directly from that buffer (see [[*Commands in the
8602 - {{{kbd(M-x org-agenda T)}}} (~org-todo-list~) ::
8604 #+kindex: T @r{(Agenda dispatcher)}
8605 #+findex: org-todo-list
8606 #+cindex: TODO keyword matching
8607 #+vindex: org-todo-keywords
8608 Like the above, but allows selection of a specific TODO keyword.
8609 You can also do this by specifying a prefix argument to
8610 {{{kbd(t)}}}. You are prompted for a keyword, and you may also
8611 specify several keywords by separating them with =|= as the boolean
8612 OR operator. With a numeric prefix, the Nth keyword in
8613 ~org-todo-keywords~ is selected.
8616 The {{{kbd(r)}}} key in the agenda buffer regenerates it, and you
8617 can give a prefix argument to this command to change the selected
8618 TODO keyword, for example {{{kbd(3 r)}}}. If you often need
8619 a search for a specific keyword, define a custom command for it (see
8620 [[*The Agenda Dispatcher]]).
8622 Matching specific TODO keywords can also be done as part of a tags
8623 search (see [[*Tag Searches]]).
8625 Remote editing of TODO items means that you can change the state of
8626 a TODO entry with a single key press. The commands available in the
8627 TODO list are described in [[*Commands in the Agenda Buffer]].
8629 #+cindex: sublevels, inclusion into TODO list
8630 Normally the global TODO list simply shows all headlines with TODO
8631 keywords. This list can become very long. There are two ways to keep
8635 #+vindex: org-agenda-todo-ignore-scheduled
8636 #+vindex: org-agenda-todo-ignore-deadlines
8637 #+vindex: org-agenda-todo-ignore-timestamp
8638 #+vindex: org-agenda-todo-ignore-with-date
8639 Some people view a TODO item that has been /scheduled/ for execution
8640 or have a /deadline/ (see [[*Timestamps, Deadlines and Scheduling]]) as
8641 no longer /open/. Configure the variables
8642 ~org-agenda-todo-ignore-scheduled~,
8643 ~org-agenda-todo-ignore-deadlines~,
8644 ~org-agenda-todo-ignore-timestamp~ and/or
8645 ~org-agenda-todo-ignore-with-date~ to exclude such items from the
8649 #+vindex: org-agenda-todo-list-sublevels
8650 TODO items may have sublevels to break up the task into subtasks.
8651 In such cases it may be enough to list only the highest level TODO
8652 headline and omit the sublevels from the global list. Configure the
8653 variable ~org-agenda-todo-list-sublevels~ to get this behavior.
8655 *** Matching tags and properties
8657 :DESCRIPTION: Structured information with fine-tuned search.
8659 #+cindex: matching, of tags
8660 #+cindex: matching, of properties
8662 #+cindex: match view
8664 If headlines in the agenda files are marked with /tags/ (see [[*Tags]]),
8665 or have properties (see [[*Properties and Columns]]), you can select
8666 headlines based on this metadata and collect them into an agenda
8667 buffer. The match syntax described here also applies when creating
8668 sparse trees with {{{kbd(C-c / m)}}}.
8670 - {{{kbd(M-x org-agenda m)}}} (~org-tags-view~) ::
8672 #+kindex: m @r{(Agenda dispatcher)}
8673 #+findex: org-tags-view
8674 Produce a list of all headlines that match a given set of tags. The
8675 command prompts for a selection criterion, which is a boolean logic
8676 expression with tags, like =+work+urgent-withboss= or =work|home=
8677 (see [[*Tags]]). If you often need a specific search, define a custom
8678 command for it (see [[*The Agenda Dispatcher]]).
8680 - {{{kbd(M-x org-agenda M)}}} (~org-tags-view~) ::
8682 #+kindex: M @r{(Agenda dispatcher)}
8683 #+findex: org-tags-view
8684 #+vindex: org-tags-match-list-sublevels
8685 #+vindex: org-agenda-tags-todo-honor-ignore-options
8686 Like {{{kbd(m)}}}, but only select headlines that are also TODO
8687 items and force checking subitems (see the variable
8688 ~org-tags-match-list-sublevels~). To exclude scheduled/deadline
8689 items, see the variable ~org-agenda-tags-todo-honor-ignore-options~.
8690 Matching specific TODO keywords together with a tags match is also
8691 possible, see [[*Tag Searches]].
8693 The commands available in the tags list are described in [[*Commands in
8694 the Agenda Buffer]].
8696 #+cindex: boolean logic, for agenda searches
8697 A search string can use Boolean operators =&= for AND and =|= for OR.
8698 =&= binds more strongly than =|=. Parentheses are currently not
8699 implemented. Each element in the search is either a tag, a regular
8700 expression matching tags, or an expression like =PROPERTY OPERATOR
8701 VALUE= with a comparison operator, accessing a property value. Each
8702 element may be preceded by =-= to select against it, and =+= is
8703 syntactic sugar for positive selection. The AND operator =&= is
8704 optional when =+= or =-= is present. Here are some examples, using
8709 Select headlines tagged =work=, but discard those also tagged
8714 Selects lines tagged =work= or =laptop=.
8716 - ~work|laptop+night~ ::
8718 Like before, but require the =laptop= lines to be tagged also
8721 #+cindex: regular expressions, with tags search
8722 Instead of a tag, you may also specify a regular expression enclosed
8723 in curly braces. For example, =work+{^boss.*}= matches headlines that
8724 contain the tag =:work:= and any tag /starting/ with =boss=.
8726 #+cindex: group tags, as regular expressions
8727 Group tags (see [[*Tag Hierarchy]]) are expanded as regular expressions.
8728 E.g., if =work= is a group tag for the group =:work:lab:conf:=, then
8729 searching for =work= also searches for ={\(?:work\|lab\|conf\)}= and
8730 searching for =-work= searches for all headlines but those with one of
8731 the tags in the group (i.e., =-{\(?:work\|lab\|conf\)}=).
8733 #+cindex: TODO keyword matching, with tags search
8734 #+cindex: level, for tags/property match
8735 #+cindex: category, for tags/property match
8736 #+vindex: org-odd-levels-only
8737 You may also test for properties (see [[*Properties and Columns]]) at the
8738 same time as matching tags. The properties may be real properties, or
8739 special properties that represent other metadata (see [[*Special
8740 Properties]]). For example, the property =TODO= represents the TODO
8741 keyword of the entry. Or, the property =LEVEL= represents the level
8742 of an entry. So searching =+LEVEL=3+boss-TODO​="DONE"= lists all level
8743 three headlines that have the tag =boss= and are /not/ marked with the
8744 TODO keyword =DONE=. In buffers with ~org-odd-levels-only~ set,
8745 =LEVEL= does not count the number of stars, but =LEVEL=2= corresponds
8748 Here are more examples:
8750 - =work+TODO​="WAITING"= ::
8752 Select =work=-tagged TODO lines with the specific TODO keyword
8755 - =work+TODO​="WAITING"|home+TODO​="WAITING"= ::
8757 Waiting tasks both at work and at home.
8759 When matching properties, a number of different operators can be used
8760 to test the value of a property. Here is a complex example:
8763 +work-boss+PRIORITY="A"+Coffee="unlimited"+Effort<2
8764 +With={Sarah|Denny}+SCHEDULED>="<2008-10-11>"
8767 #+texinfo: @noindent
8768 The type of comparison depends on how the comparison value is written:
8770 - If the comparison value is a plain number, a numerical comparison is
8771 done, and the allowed operators are =<=, ===, =>=, =<==, =>==, and
8774 - If the comparison value is enclosed in double-quotes, a string
8775 comparison is done, and the same operators are allowed.
8777 - If the comparison value is enclosed in double-quotes /and/ angular
8778 brackets (like =DEADLINE<​="<2008-12-24 18:30>"=), both values are
8779 assumed to be date/time specifications in the standard Org way, and
8780 the comparison is done accordingly. Valid values also include
8781 ="<now>"= for now (including time), ="<today>"=, and ="<tomorrow>"=
8782 for these days at 0:00 hours, i.e., without a time specification.
8783 You can also use strings like ="<+5d>"= or ="<-2m>"= with units =d=,
8784 =w=, =m=, and =y= for day, week, month, and year, respectively.
8786 - If the comparison value is enclosed in curly braces, a regexp match
8787 is performed, with === meaning that the regexp matches the property
8788 value, and =<>= meaning that it does not match.
8790 So the search string in the example finds entries tagged =work= but
8791 not =boss=, which also have a priority value =A=, a =Coffee= property
8792 with the value =unlimited=, an =EFFORT= property that is numerically
8793 smaller than 2, a =With= property that is matched by the regular
8794 expression =Sarah|Denny=, and that are scheduled on or after October
8797 You can configure Org mode to use property inheritance during
8798 a search, but beware that this can slow down searches considerably.
8799 See [[*Property Inheritance]], for details.
8801 For backward compatibility, and also for typing speed, there is also
8802 a different way to test TODO states in a search. For this, terminate
8803 the tags/property part of the search string (which may include several
8804 terms connected with =|=) with a =/= and then specify a Boolean
8805 expression just for TODO keywords. The syntax is then similar to that
8806 for tags, but should be applied with care: for example, a positive
8807 selection on several TODO keywords cannot meaningfully be combined
8808 with boolean AND. However, /negative selection/ combined with AND can
8809 be meaningful. To make sure that only lines are checked that actually
8810 have any TODO keyword (resulting in a speed-up), use {{{kbd(M-x
8811 org-agenda M)}}}, or equivalently start the TODO part after the slash
8812 with =!=. Using {{{kbd(M-x org-agenda M)}}} or =/!= does not match
8813 TODO keywords in a DONE state. Examples:
8817 Same as =work+TODO​="WAITING"=.
8819 - =work/!-WAITING-NEXT= ::
8821 Select =work=-tagged TODO lines that are neither =WAITING= nor
8824 - =work/!+WAITING|+NEXT= ::
8826 Select =work=-tagged TODO lines that are either =WAITING= or =NEXT=.
8830 :DESCRIPTION: Find entries by searching for text.
8832 #+cindex: search view
8833 #+cindex: text search
8834 #+cindex: searching, for text
8836 This agenda view is a general text search facility for Org mode
8837 entries. It is particularly useful to find notes.
8839 - {{{kbd(M-x org-agenda s)}}} (~org-search-view~) ::
8841 #+kindex: s @r{(Agenda dispatcher)}
8842 #+findex: org-search-view
8843 This is a special search that lets you select entries by matching
8844 a substring or specific words using a boolean logic.
8846 For example, the search string =computer equipment= matches entries
8847 that contain =computer equipment= as a substring, even if the two
8848 words are separated by more space or a line break.
8850 Search view can also search for specific keywords in the entry, using
8851 Boolean logic. The search string =+computer
8852 +wifi -ethernet -{8\.11[bg]}= matches note entries that contain the
8853 keywords =computer= and =wifi=, but not the keyword =ethernet=, and
8854 which are also not matched by the regular expression =8\.11[bg]=,
8855 meaning to exclude both =8.11b= and =8.11g=. The first =+= is
8856 necessary to turn on boolean search, other =+= characters are
8857 optional. For more details, see the docstring of the command
8860 You can incrementally adjust a boolean search with the following keys
8862 #+attr_texinfo: :columns 0.1 0.6
8863 | {{{kbd([)}}} | Add a positive search word |
8864 | {{{kbd(])}}} | Add a negative search word |
8865 | {{{kbd({)}}} | Add a positive regular expression |
8866 | {{{kbd(})}}} | Add a negative regular expression |
8868 #+vindex: org-agenda-text-search-extra-files
8869 Note that in addition to the agenda files, this command also searches
8870 the files listed in ~org-agenda-text-search-extra-files~.
8874 :DESCRIPTION: Find projects you need to review.
8876 #+pindex: GTD, Getting Things Done
8878 If you are following a system like David Allen's GTD to organize your
8879 work, one of the "duties" you have is a regular review to make sure
8880 that all projects move along. A /stuck/ project is a project that has
8881 no defined next actions, so it never shows up in the TODO lists Org
8882 mode produces. During the review, you need to identify such projects
8883 and define next actions for them.
8885 - {{{kbd(M-x org-agenda #)}}} (~org-agenda-list-stuck-projects~) ::
8887 #+kindex: # @r{(Agenda dispatcher)}
8888 #+findex: org-agenda-list-stuck-projects
8889 List projects that are stuck.
8891 - {{{kbd(M-x org-agenda !)}}} ::
8893 #+kindex: ! @r{(Agenda dispatcher)}
8894 #+vindex: org-stuck-projects
8895 Customize the variable ~org-stuck-projects~ to define what a stuck
8896 project is and how to find it.
8898 You almost certainly need to configure this view before it works for
8899 you. The built-in default assumes that all your projects are level-2
8900 headlines, and that a project is not stuck if it has at least one
8901 entry marked with a TODO keyword =TODO= or =NEXT= or =NEXTACTION=.
8903 Let's assume that you, in your own way of using Org mode, identify
8904 projects with a tag =:PROJECT:=, and that you use a TODO keyword
8905 =MAYBE= to indicate a project that should not be considered yet.
8906 Let's further assume that the TODO keyword =DONE= marks finished
8907 projects, and that =NEXT= and =TODO= indicate next actions. The tag
8908 =:@shop:= indicates shopping and is a next action even without the
8909 NEXT tag. Finally, if the project contains the special word =IGNORE=
8910 anywhere, it should not be listed either. In this case you would
8911 start by identifying eligible projects with a tags/TODO match (see
8912 [[*Tag Searches]]) =+PROJECT/-MAYBE-DONE=, and then check for =TODO=,
8913 =NEXT=, =@shop=, and =IGNORE= in the subtree to identify projects that
8914 are not stuck. The correct customization for this is:
8916 #+begin_src emacs-lisp
8917 (setq org-stuck-projects
8918 '("+PROJECT/-MAYBE-DONE" ("NEXT" "TODO") ("@shop")
8922 Note that if a project is identified as non-stuck, the subtree of this
8923 entry is searched for stuck projects.
8925 ** Presentation and Sorting
8927 :DESCRIPTION: How agenda items are prepared for display.
8929 #+cindex: presentation, of agenda items
8931 #+vindex: org-agenda-prefix-format
8932 #+vindex: org-agenda-tags-column
8933 Before displaying items in an agenda view, Org mode visually prepares
8934 the items and sorts them. Each item occupies a single line. The line
8935 starts with a /prefix/ that contains the /category/ (see [[*Categories]])
8936 of the item and other important information. You can customize in
8937 which column tags are displayed through ~org-agenda-tags-column~. You
8938 can also customize the prefix using the option
8939 ~org-agenda-prefix-format~. This prefix is followed by a cleaned-up
8940 version of the outline headline associated with the item.
8944 :DESCRIPTION: Not all tasks are equal.
8947 #+cindex: @samp{CATEGORY}, keyword
8949 The category is a broad label assigned to each agenda item. By
8950 default, the category is simply derived from the file name, but you
8951 can also specify it with a special line in the buffer, like
8954 : #+CATEGORY: Thesis
8956 #+cindex: @samp{CATEGORY}, property
8957 If you would like to have a special category for a single entry or
8958 a (sub)tree, give the entry a =CATEGORY= property with the special
8959 category you want to apply as the value.
8961 The display in the agenda buffer looks best if the category is not
8962 longer than 10 characters.
8964 #+vindex: org-agenda-category-icon-alist
8965 You can set up icons for category by customizing the
8966 ~org-agenda-category-icon-alist~ variable.
8968 *** Time-of-day specifications
8970 :DESCRIPTION: How the agenda knows the time.
8972 #+cindex: time-of-day specification
8974 Org mode checks each agenda item for a time-of-day specification. The
8975 time can be part of the timestamp that triggered inclusion into the
8978 : <2005-05-10 Tue 19:00>
8980 #+texinfo: @noindent
8981 Time ranges can be specified with two timestamps:
8983 : <2005-05-10 Tue 20:30>--<2005-05-10 Tue 22:15>
8985 #+vindex: org-agenda-search-headline-for-time
8986 In the headline of the entry itself, a time(range)---like =12:45= or
8987 a =8:30-1pm=---may also appear as plain text[fn:97].
8989 If the agenda integrates the Emacs diary (see [[*Weekly/daily agenda]]),
8990 time specifications in diary entries are recognized as well.
8992 For agenda display, Org mode extracts the time and displays it in
8993 a standard 24 hour format as part of the prefix. The example times in
8994 the previous paragraphs would end up in the agenda like this:
8997 8:30-13:00 Arthur Dent lies in front of the bulldozer
8998 12:45...... Ford Prefect arrives and takes Arthur to the pub
8999 19:00...... The Vogon reads his poem
9000 20:30-22:15 Marvin escorts the Hitchhikers to the bridge
9004 If the agenda is in single-day mode, or for the display of today, the
9005 timed entries are embedded in a time grid, like
9008 8:00...... ------------------
9009 8:30-13:00 Arthur Dent lies in front of the bulldozer
9010 10:00...... ------------------
9011 12:00...... ------------------
9012 12:45...... Ford Prefect arrives and takes Arthur to the pub
9013 14:00...... ------------------
9014 16:00...... ------------------
9015 18:00...... ------------------
9016 19:00...... The Vogon reads his poem
9017 20:00...... ------------------
9018 20:30-22:15 Marvin escorts the Hitchhikers to the bridge
9021 #+vindex: org-agenda-use-time-grid
9022 #+vindex: org-agenda-time-grid
9023 The time grid can be turned on and off with the variable
9024 ~org-agenda-use-time-grid~, and can be configured with
9025 ~org-agenda-time-grid~.
9027 *** Sorting of agenda items
9029 :DESCRIPTION: The order of things.
9031 #+cindex: sorting, of agenda items
9032 #+cindex: priorities, of agenda items
9034 Before being inserted into a view, the items are sorted. How this is
9035 done depends on the type of view.
9038 #+vindex: org-agenda-files
9039 For the daily/weekly agenda, the items for each day are sorted. The
9040 default order is to first collect all items containing an explicit
9041 time-of-day specification. These entries are shown at the beginning
9042 of the list, as a /schedule/ for the day. After that, items remain
9043 grouped in categories, in the sequence given by ~org-agenda-files~.
9044 Within each category, items are sorted by priority (see
9045 [[*Priorities]]), which is composed of the base priority (2000 for
9046 priority =A=, 1000 for =B=, and 0 for =C=), plus additional
9047 increments for overdue scheduled or deadline items.
9049 - For the TODO list, items remain in the order of categories, but
9050 within each category, sorting takes place according to priority (see
9051 [[*Priorities]]). The priority used for sorting derives from the
9052 priority cookie, with additions depending on how close an item is to
9053 its due or scheduled date.
9055 - For tags matches, items are not sorted at all, but just appear in
9056 the sequence in which they are found in the agenda files.
9058 #+vindex: org-agenda-sorting-strategy
9059 Sorting can be customized using the variable
9060 ~org-agenda-sorting-strategy~, and may also include criteria based on
9061 the estimated effort of an entry (see [[*Effort Estimates]]).
9063 *** Filtering/limiting agenda times
9065 :DESCRIPTION: Dynamically narrow the agenda.
9068 Agenda built-in or customized commands are statically defined. Agenda
9069 filters and limits provide two ways of dynamically narrowing down the
9070 list of agenda entries: /filters/ and /limits/. Filters only act on
9071 the display of the items, while limits take effect before the list of
9072 agenda entries is built. Filters are more often used interactively,
9073 while limits are mostly useful when defined as local variables within
9074 custom agenda commands.
9076 **** Filtering in the agenda
9080 #+cindex: agenda filtering
9081 #+cindex: filtering entries, in agenda
9082 #+cindex: tag filtering, in agenda
9083 #+cindex: category filtering, in agenda
9084 #+cindex: top headline filtering, in agenda
9085 #+cindex: effort filtering, in agenda
9086 #+cindex: query editing, in agenda
9088 - {{{kbd(/)}}} (~org-agenda-filter-by-tag~) ::
9090 #+findex: org-agenda-filter-by-tag
9091 #+vindex: org-agenda-tag-filter-preset
9092 Filter the agenda view with respect to a tag and/or effort
9093 estimates. The difference between this and a custom agenda command
9094 is that filtering is very fast, so that you can switch quickly
9095 between different filters without having to recreate the
9098 You are prompted for a tag selection letter; {{{kbd(SPC)}}} means
9099 any tag at all. Pressing {{{kbd(TAB)}}} at that prompt offers
9100 completion to select a tag, including any tags that do not have
9101 a selection character. The command then hides all entries that do
9102 not contain or inherit this tag. When called with prefix argument,
9103 remove the entries that /do/ have the tag. A second {{{kbd(/)}}} at
9104 the prompt turns off the filter and shows any hidden entries.
9105 Pressing {{{kbd(+)}}} or {{{kbd(-)}}} switches between filtering and
9106 excluding the next tag.
9108 #+vindex: org-agenda-auto-exclude-function
9109 Org also supports automatic, context-aware tag filtering. If the
9110 variable ~org-agenda-auto-exclude-function~ is set to a user-defined
9111 function, that function can decide which tags should be excluded
9112 from the agenda automatically. Once this is set, the {{{kbd(/)}}}
9113 command then accepts {{{kbd(RET)}}} as a sub-option key and runs the
9114 auto exclusion logic. For example, let's say you use a =Net= tag to
9115 identify tasks which need network access, an =Errand= tag for
9116 errands in town, and a =Call= tag for making phone calls. You could
9117 auto-exclude these tags based on the availability of the Internet,
9118 and outside of business hours, with something like this:
9120 #+begin_src emacs-lisp
9121 (defun org-my-auto-exclude-function (tag)
9123 ((string= tag "Net")
9124 (/= 0 (call-process "/sbin/ping" nil nil nil
9125 "-c1" "-q" "-t1" "mail.gnu.org")))
9126 ((or (string= tag "Errand") (string= tag "Call"))
9127 (let ((hour (nth 2 (decode-time))))
9128 (or (< hour 8) (> hour 21)))))
9131 (setq org-agenda-auto-exclude-function 'org-my-auto-exclude-function)
9134 - {{{kbd(<)}}} (~org-agenda-filter-by-category~) ::
9136 #+findex: org-agenda-filter-by-category
9137 Filter the current agenda view with respect to the category of the
9138 item at point. Pressing {{{kbd(<)}}} another time removes this
9139 filter. When called with a prefix argument exclude the category of
9140 the item at point from the agenda.
9142 #+vindex: org-agenda-category-filter-preset
9143 You can add a filter preset in custom agenda commands through the
9144 option ~org-agenda-category-filter-preset~. See [[*Setting options
9145 for custom commands]].
9147 - {{{kbd(^)}}} (~org-agenda-filter-by-top-headline~) ::
9149 #+findex: org-agenda-filter-by-top-headline
9150 Filter the current agenda view and only display the siblings and the
9151 parent headline of the one at point.
9153 - {{{kbd(=)}}} (~org-agenda-filter-by-regexp~) ::
9155 #+findex: org-agenda-filter-by-regexp
9156 Filter the agenda view by a regular expression: only show agenda
9157 entries matching the regular expression the user entered. When
9158 called with a prefix argument, it filters /out/ entries matching the
9159 regexp. Called in a regexp-filtered agenda view, remove the filter,
9160 unless there are two universal prefix arguments, in which case
9161 filters are cumulated.
9163 #+vindex: org-agenda-regexp-filter-preset
9164 You can add a filter preset in custom agenda commands through the
9165 option ~org-agenda-regexp-filter-preset~. See [[*Setting options
9166 for custom commands]].
9168 - {{{kbd(_)}}} (~org-agenda-filter-by-effort~) ::
9170 #+findex: org-agenda-filter-by-effort
9171 Filter the agenda view with respect to effort estimates. You first
9172 need to set up allowed efforts globally, for example
9174 #+begin_src emacs-lisp
9175 (setq org-global-properties
9176 '(("Effort_ALL". "0 0:10 0:30 1:00 2:00 3:00 4:00")))
9179 #+vindex: org-sort-agenda-noeffort-is-high
9180 You can then filter for an effort by first typing an operator, one
9181 of {{{kbd(<)}}}, {{{kbd(>)}}} and {{{kbd(=)}}}, and then the
9182 one-digit index of an effort estimate in your array of allowed
9183 values, where {{{kbd(0)}}} means the 10th value. The filter then
9184 restricts to entries with effort smaller-or-equal, equal, or
9185 larger-or-equal than the selected value. For application of the
9186 operator, entries without a defined effort are treated according to
9187 the value of ~org-sort-agenda-noeffort-is-high~.
9189 When called with a prefix argument, it removes entries matching the
9190 condition. With two universal prefix arguments, it clears effort
9191 filters, which can be accumulated.
9193 #+vindex: org-agenda-effort-filter-preset
9194 You can add a filter preset in custom agenda commands through the
9195 option ~org-agenda-effort-filter-preset~. See [[*Setting options for
9198 - {{{kbd(|)}}} (~org-agenda-filter-remove-all~) ::
9200 Remove all filters in the current agenda view.
9202 **** Setting limits for the agenda
9206 #+cindex: limits, in agenda
9208 Here is a list of options that you can set, either globally, or
9209 locally in your custom agenda views (see [[*Custom Agenda Views]]).
9211 - ~org-agenda-max-entries~ ::
9213 #+vindex: org-agenda-max-entries
9214 Limit the number of entries.
9216 - ~org-agenda-max-effort~ ::
9218 #+vindex: org-agenda-max-effort
9219 Limit the duration of accumulated efforts (as minutes).
9221 - ~org-agenda-max-todos~ ::
9223 #+vindex: org-agenda-max-todos
9224 Limit the number of entries with TODO keywords.
9226 - ~org-agenda-max-tags~ ::
9228 #+vindex: org-agenda-max-tags
9229 Limit the number of tagged entries.
9231 When set to a positive integer, each option excludes entries from
9232 other categories: for example, =(setq org-agenda-max-effort 100)=
9233 limits the agenda to 100 minutes of effort and exclude any entry that
9234 has no effort property. If you want to include entries with no effort
9235 property, use a negative value for ~org-agenda-max-effort~. One
9236 useful setup is to use ~org-agenda-max-entries~ locally in a custom
9237 command. For example, this custom command displays the next five
9238 entries with a =NEXT= TODO keyword.
9240 #+begin_src emacs-lisp
9241 (setq org-agenda-custom-commands
9243 ((org-agenda-max-entries 5)))))
9246 Once you mark one of these five entry as DONE, rebuilding the agenda
9247 will again the next five entries again, including the first entry that
9248 was excluded so far.
9250 You can also dynamically set temporary limits, which are lost when
9251 rebuilding the agenda:
9253 - {{{kbd(~ )}}} (~org-agenda-limit-interactively~) ::
9255 #+findex: org-agenda-limit-interactively
9256 This prompts for the type of limit to apply and its value.
9258 ** Commands in the Agenda Buffer
9260 :DESCRIPTION: Remote editing of Org trees.
9261 :ALT_TITLE: Agenda Commands
9263 #+cindex: commands, in agenda buffer
9265 Entries in the agenda buffer are linked back to the Org file or diary
9266 file where they originate. You are not allowed to edit the agenda
9267 buffer itself, but commands are provided to show and jump to the
9268 original entry location, and to edit the Org files "remotely" from the
9269 agenda buffer. In this way, all information is stored only once,
9270 removing the risk that your agenda and note files may diverge.
9272 Some commands can be executed with mouse clicks on agenda lines. For
9273 the other commands, point needs to be in the desired line.
9279 #+cindex: motion commands in agenda
9281 - {{{kbd(n)}}} (~org-agenda-next-line~) ::
9284 #+findex: org-agenda-next-line
9285 Next line (same as {{{kbd(DOWN)}}} and {{{kbd(C-n)}}}).
9287 - {{{kbd(p)}}} (~org-agenda-previous-line~) ::
9290 #+findex: org-agenda-previous-line
9291 Previous line (same as {{{kbd(UP)}}} and {{{kbd(C-p)}}}).
9293 *** View/Go to Org file
9297 #+cindex: view file commands in agenda
9299 - {{{kbd(SPC)}}} or {{{kbd(mouse-3)}}} (~org-agenda-show-and-scroll-up~) ::
9303 #+findex: org-agenda-show-and-scroll-up
9304 Display the original location of the item in another window.
9305 With a prefix argument, make sure that drawers stay folded.
9307 - {{{kbd(L)}}} (~org-agenda-recenter~) ::
9309 #+findex: org-agenda-recenter
9310 Display original location and recenter that window.
9312 - {{{kbd(TAB)}}} or {{{kbd(mouse-2)}}} (~org-agenda-goto~) ::
9316 #+findex: org-agenda-goto
9317 Go to the original location of the item in another window.
9319 - {{{kbd(RET)}}} (~org-agenda-switch-to~) ::
9322 #+findex: org-agenda-switch-to
9323 Go to the original location of the item and delete other windows.
9325 - {{{kbd(F)}}} (~org-agenda-follow-mode~) ::
9328 #+findex: org-agenda-follow-mode
9329 #+vindex: org-agenda-start-with-follow-mode
9330 Toggle Follow mode. In Follow mode, as you move point through the
9331 agenda buffer, the other window always shows the corresponding
9332 location in the Org file. The initial setting for this mode in new
9333 agenda buffers can be set with the variable
9334 ~org-agenda-start-with-follow-mode~.
9336 - {{{kbd(C-c C-x b)}}} (~org-agenda-tree-to-indirect-buffer~) ::
9339 #+findex: org-agenda-tree-to-indirect-buffer
9340 Display the entire subtree of the current item in an indirect
9341 buffer. With a numeric prefix argument N, go up to level N and then
9342 take that tree. If N is negative, go up that many levels. With
9343 a {{{kbd(C-u)}}} prefix, do not remove the previously used indirect
9346 - {{{kbd(C-c C-o)}}} (~org-agenda-open-link~) ::
9349 #+findex: org-agenda-open-link
9350 Follow a link in the entry. This offers a selection of any links in
9351 the text belonging to the referenced Org node. If there is only one
9352 link, follow it without a selection prompt.
9358 #+cindex: change agenda display
9359 #+cindex: display changing, in agenda
9361 #+attr_texinfo: :sep ,
9365 Interactively select another agenda view and append it to the
9371 Delete other windows.
9373 - {{{kbd(v d)}}} or short {{{kbd(d)}}} (~org-agenda-day-view~) ::
9377 #+findex: org-agenda-day-view
9378 Switch to day view. When switching to day view, this setting
9379 becomes the default for subsequent agenda refreshes. A numeric
9380 prefix argument may be used to jump directly to a specific day of
9381 the year. For example, {{{kbd(32 d)}}} jumps to February 1st. When
9382 setting day view, a year may be encoded in the prefix argument as
9383 well. For example, {{{kbd(200712 d)}}} jumps to January 12, 2007.
9384 If such a year specification has only one or two digits, it is
9385 expanded into one of the 30 next years or the last 69 years.
9387 - {{{kbd(v w)}}} or short {{{kbd(w)}}} (~org-agenda-week-view~) ::
9391 #+findex: org-agenda-week-view
9392 Switch to week view. When switching week view, this setting becomes
9393 the default for subsequent agenda refreshes. A numeric prefix
9394 argument may be used to jump directly to a specific day of the ISO
9395 week. For example {{{kbd(9 w)}}} to ISO week number 9. When
9396 setting week view, a year may be encoded in the prefix argument as
9397 well. For example, {{{kbd(200712 w)}}} jumps to week 12 in 2007.
9398 If such a year specification has only one or two digits, it is
9399 expanded into one of the 30 next years or the last 69 years.
9401 - {{{kbd(v m)}}} (~org-agenda-month-view~) ::
9404 #+findex: org-agenda-month-view
9405 Switch to month view. Because month views are slow to create, they
9406 do not become the default for subsequent agenda refreshes.
9407 A numeric prefix argument may be used to jump directly to a specific
9408 day of the month. When setting month view, a year may be encoded in
9409 the prefix argument as well. For example, {{{kbd(200712 m)}}} jumps
9410 to December, 2007. If such a year specification has only one or two
9411 digits, it is expanded into one of the 30 next years or the last 69
9414 - {{{kbd(v y)}}} (~org-agenda-year-view~) ::
9417 #+findex: org-agenda-year-view
9418 Switch to year view. Because year views are slow to create, they do
9419 not become the default for subsequent agenda refreshes. A numeric
9420 prefix argument may be used to jump directly to a specific day of
9423 - {{{kbd(v SPC)}}} (~org-agenda-reset-view~) ::
9426 #+findex: org-agenda-reset-view
9427 #+vindex: org-agenda-span
9428 Reset the current view to ~org-agenda-span~.
9430 - {{{kbd(f)}}} (~org-agenda-later~) ::
9433 #+findex: org-agenda-later
9434 Go forward in time to display the span following the current one.
9435 For example, if the display covers a week, switch to the following
9436 week. With a prefix argument, repeat that many times.
9438 - {{{kbd(b)}}} (~org-agenda-earlier~) ::
9441 #+findex: org-agenda-earlier
9442 Go backward in time to display earlier dates.
9444 - {{{kbd(.)}}} (~org-agenda-goto-today~) ::
9447 #+findex: org-agenda-goto-today
9450 - {{{kbd(j)}}} (~org-agenda-goto-date~) ::
9453 #+findex: org-agenda-goto-date
9454 Prompt for a date and go there.
9456 - {{{kbd(J)}}} (~org-agenda-clock-goto~) ::
9459 #+findex: org-agenda-clock-goto
9460 Go to the currently clocked-in task /in the agenda buffer/.
9462 - {{{kbd(D)}}} (~org-agenda-toggle-diary~) ::
9465 #+findex: org-agenda-toggle-diary
9466 Toggle the inclusion of diary entries. See [[*Weekly/daily agenda]].
9468 - {{{kbd(v l)}}} or {{{kbd(v L)}}} or short {{{kbd(l)}}} (~org-agenda-log-mode~) ::
9473 #+findex: org-agenda-log-mode
9474 #+vindex: org-log-done
9475 #+vindex: org-agenda-log-mode-items
9476 Toggle Logbook mode. In Logbook mode, entries that were marked DONE
9477 while logging was on (see the variable ~org-log-done~) are shown in
9478 the agenda, as are entries that have been clocked on that day. You
9479 can configure the entry types that should be included in log mode
9480 using the variable ~org-agenda-log-mode-items~. When called with
9481 a {{{kbd(C-u)}}} prefix, show all possible logbook entries,
9482 including state changes. When called with two prefix arguments
9483 {{{kbd(C-u C-u)}}}, show only logging information, nothing else.
9484 {{{kbd(v L)}}} is equivalent to {{{kbd(C-u v l)}}}.
9486 - {{{kbd(v [)}}} or short {{{kbd([)}}} (~org-agenda-manipulate-query-add~) ::
9490 #+findex: org-agenda-manipulate-query-add
9491 Include inactive timestamps into the current view. Only for
9492 weekly/daily agenda.
9494 - {{{kbd(v a)}}} (~org-agenda-archives-mode~) ::
9497 #+findex: org-agenda-archives-mode
9498 Toggle Archives mode. In Archives mode, trees that are archived
9499 (see [[*Internal archiving]]) are also scanned when producing the
9500 agenda. To exit archives mode, press {{{kbd(v a)}}} again.
9505 Toggle Archives mode. Include all archive files as well.
9507 - {{{kbd(v R)}}} or short {{{kbd(R)}}} (~org-agenda-clockreport-mode~) ::
9511 #+findex: org-agenda-clockreport-mode
9512 #+vindex: org-agenda-start-with-clockreport-mode
9513 #+vindex: org-clock-report-include-clocking-task
9514 Toggle Clockreport mode. In Clockreport mode, the daily/weekly
9515 agenda always shows a table with the clocked times for the time span
9516 and file scope covered by the current agenda view. The initial
9517 setting for this mode in new agenda buffers can be set with the
9518 variable ~org-agenda-start-with-clockreport-mode~. By using
9519 a prefix argument when toggling this mode (i.e., {{{kbd(C-u R)}}}),
9520 the clock table does not show contributions from entries that are
9521 hidden by agenda filtering[fn:99]. See also the variable
9522 ~org-clock-report-include-clocking-task~.
9527 #+vindex: org-agenda-clock-consistency-checks
9528 Show overlapping clock entries, clocking gaps, and other clocking
9529 problems in the current agenda range. You can then visit clocking
9530 lines and fix them manually. See the variable
9531 ~org-agenda-clock-consistency-checks~ for information on how to
9532 customize the definition of what constituted a clocking problem. To
9533 return to normal agenda display, press {{{kbd(l)}}} to exit Logbook
9536 - {{{kbd(v E)}}} or short {{{kbd(E)}}} (~org-agenda-entry-text-mode~) ::
9540 #+findex: org-agenda-entry-text-mode
9541 #+vindex: org-agenda-start-with-entry-text-mode
9542 #+vindex: org-agenda-entry-text-maxlines
9543 Toggle entry text mode. In entry text mode, a number of lines from
9544 the Org outline node referenced by an agenda line are displayed
9545 below the line. The maximum number of lines is given by the
9546 variable ~org-agenda-entry-text-maxlines~. Calling this command
9547 with a numeric prefix argument temporarily modifies that number to
9550 - {{{kbd(G)}}} (~org-agenda-toggle-time-grid~) ::
9553 #+vindex: org-agenda-use-time-grid
9554 #+vindex: org-agenda-time-grid
9555 Toggle the time grid on and off. See also the variables
9556 ~org-agenda-use-time-grid~ and ~org-agenda-time-grid~.
9558 - {{{kbd(r)}}} (~org-agenda-redo~), {{{kbd(g)}}} ::
9562 #+findex: org-agenda-redo
9563 Recreate the agenda buffer, for example to reflect the changes after
9564 modification of the timestamps of items with {{{kbd(S-LEFT)}}} and
9565 {{{kbd(S-RIGHT)}}}. When the buffer is the global TODO list,
9566 a prefix argument is interpreted to create a selective list for
9567 a specific TODO keyword.
9569 - {{{kbd(C-x C-s)}}} or short {{{kbd(s)}}} (~org-save-all-org-buffers~) ::
9572 #+findex: org-save-all-org-buffers
9574 Save all Org buffers in the current Emacs session, and also the
9577 - {{{kbd(C-c C-x C-c)}}} (~org-agenda-columns~) ::
9579 #+kindex: C-c C-x C-c
9580 #+findex: org-agenda-columns
9581 #+vindex: org-columns-default-format
9582 Invoke column view (see [[*Column View]]) in the agenda buffer. The
9583 column view format is taken from the entry at point, or, if there is
9584 no entry at point, from the first entry in the agenda view. So
9585 whatever the format for that entry would be in the original buffer
9586 (taken from a property, from a =COLUMNS= keyword, or from the
9587 default variable ~org-columns-default-format~) is used in the
9590 - {{{kbd(C-c C-x >)}}} (~org-agenda-remove-restriction-lock~) ::
9593 #+findex: org-agenda-remove-restriction-lock
9594 Remove the restriction lock on the agenda, if it is currently
9595 restricted to a file or subtree (see [[*Agenda Files]]).
9597 - {{{kbd(M-UP)}}} (~org-agenda-drag-line-backward~) ::
9600 #+findex: org-agenda-drag-line-backward
9601 Drag the line at point backward one line. With a numeric prefix
9602 argument, drag backward by that many lines.
9604 Moving agenda lines does not persist after an agenda refresh and
9605 does not modify the contributing Org files.
9607 - {{{kbd(M-DOWN)}}} (~org-agenda-drag-line-forward~) ::
9610 #+findex: org-agenda-drag-line-forward
9611 Drag the line at point forward one line. With a numeric prefix
9612 argument, drag forward by that many lines.
9618 #+cindex: remote editing, from agenda
9620 - {{{kbd(0--9)}}} ::
9624 - {{{kbd(C-_)}}} (~org-agenda-undo~) ::
9627 #+findex: org-agenda-undo
9628 #+cindex: undoing remote-editing events
9629 #+cindex: remote editing, undo
9630 Undo a change due to a remote editing command. The change is undone
9631 both in the agenda buffer and in the remote buffer.
9633 - {{{kbd(t)}}} (~org-agenda-todo~) ::
9636 #+findex: org-agenda-todo
9637 Change the TODO state of the item, both in the agenda and in the
9640 - {{{kbd(C-S-RIGHT)}}} (~org-agenda-todo-nextset~) ::
9643 #+findex: org-agenda-todo-nextset
9644 Switch to the next set of TODO keywords.
9646 - {{{kbd(C-S-LEFT)}}}, ~org-agenda-todo-previousset~ ::
9649 Switch to the previous set of TODO keywords.
9651 - {{{kbd(C-k)}}} (~org-agenda-kill~) ::
9654 #+findex: org-agenda-kill
9655 #+vindex: org-agenda-confirm-kill
9656 Delete the current agenda item along with the entire subtree
9657 belonging to it in the original Org file. If the text to be deleted
9658 remotely is longer than one line, the kill needs to be confirmed by
9659 the user. See variable ~org-agenda-confirm-kill~.
9661 - {{{kbd(C-c C-w)}}} (~org-agenda-refile~) ::
9664 #+findex: org-agenda-refile
9665 Refile the entry at point.
9667 - {{{kbd(C-c C-x C-a)}}} or short {{{kbd(a)}}} (~org-agenda-archive-default-with-confirmation~) ::
9669 #+kindex: C-c C-x C-a
9671 #+findex: org-agenda-archive-default-with-confirmation
9672 #+vindex: org-archive-default-command
9673 Archive the subtree corresponding to the entry at point using the
9674 default archiving command set in ~org-archive-default-command~.
9675 When using the {{{kbd(a)}}} key, confirmation is required.
9677 - {{{kbd(C-c C-x a)}}} (~org-agenda-toggle-archive-tag~) ::
9680 #+findex: org-agenda-toggle-archive-tag
9681 Toggle the archive tag (see [[*Internal archiving]]) for the current
9684 - {{{kbd(C-c C-x A)}}} (~org-agenda-archive-to-archive-sibling~) ::
9687 #+findex: org-agenda-archive-to-archive-sibling
9688 Move the subtree corresponding to the current entry to its /archive
9691 - {{{kbd(C-c C-x C-s)}}} or short {{{kbd($)}}} (~org-agenda-archive~) ::
9693 #+kindex: C-c C-x C-s
9695 #+findex: org-agenda-archive
9696 Archive the subtree corresponding to the current headline. This
9697 means the entry is moved to the configured archive location, most
9698 likely a different file.
9700 - {{{kbd(T)}}} (~org-agenda-show-tags~) ::
9703 #+findex: org-agenda-show-tags
9704 #+vindex: org-agenda-show-inherited-tags
9705 Show all tags associated with the current item. This is useful if
9706 you have turned off ~org-agenda-show-inherited-tags~, but still want
9707 to see all tags of a headline occasionally.
9709 - {{{kbd(:)}}} (~org-agenda-set-tags~) ::
9712 #+findex: org-agenda-set-tags
9713 Set tags for the current headline. If there is an active region in
9714 the agenda, change a tag for all headings in the region.
9716 - {{{kbd(\,)}}} (~org-agenda-priority~) ::
9719 #+findex: org-agenda-priority
9720 Set the priority for the current item. Org mode prompts for the
9721 priority character. If you reply with {{{kbd(SPC)}}}, the priority
9722 cookie is removed from the entry.
9724 - {{{kbd(P)}}} (~org-agenda-show-priority~) ::
9727 #+findex: org-agenda-show-priority
9728 Display weighted priority of current item.
9730 - {{{kbd(+)}}} or {{{kbd(S-UP)}}} (~org-agenda-priority-up~) ::
9734 #+findex: org-agenda-priority-up
9735 Increase the priority of the current item. The priority is changed
9736 in the original buffer, but the agenda is not resorted. Use the
9737 {{{kbd(r)}}} key for this.
9739 - {{{kbd(-)}}} or {{{kbd(S-DOWN)}}} (~org-agenda-priority-down~) ::
9743 #+findex: org-agenda-priority-down
9744 Decrease the priority of the current item.
9746 - {{{kbd(C-c C-z)}}} or short {{{kbd(z)}}} (~org-agenda-add-note~) ::
9750 #+findex: org-agenda-add-note
9751 #+vindex: org-log-into-drawer
9752 Add a note to the entry. This note is recorded, and then filed to
9753 the same location where state change notes are put. Depending on
9754 ~org-log-into-drawer~, this may be inside a drawer.
9756 - {{{kbd(C-c C-a)}}} (~org-attach~) ::
9759 #+findex: org-attach
9760 Dispatcher for all command related to attachments.
9762 - {{{kbd(C-c C-s)}}} (~org-agenda-schedule~) ::
9765 #+findex: org-agenda-schedule
9766 Schedule this item. With a prefix argument, remove the
9767 scheduling timestamp
9769 - {{{kbd(C-c C-d)}}} (~org-agenda-deadline~) ::
9772 #+findex: org-agenda-deadline
9773 Set a deadline for this item. With a prefix argument, remove the
9776 - {{{kbd(S-RIGHT)}}} (~org-agenda-do-date-later~) ::
9779 #+findex: org-agenda-do-date-later
9780 Change the timestamp associated with the current line by one day
9781 into the future. If the date is in the past, the first call to this
9782 command moves it to today. With a numeric prefix argument, change
9783 it by that many days. For example, {{{kbd(3 6 5 S-RIGHT)}}} changes
9784 it by a year. With a {{{kbd(C-u)}}} prefix, change the time by one
9785 hour. If you immediately repeat the command, it will continue to
9786 change hours even without the prefix argument. With a double
9787 {{{kbd(C-u C-u)}}} prefix, do the same for changing minutes. The
9788 stamp is changed in the original Org file, but the change is not
9789 directly reflected in the agenda buffer. Use {{{kbd(r)}}} or
9790 {{{kbd(g)}}} to update the buffer.
9792 - {{{kbd(S-LEFT)}}} (~org-agenda-do-date-earlier~) ::
9795 #+findex: org-agenda-do-date-earlier
9796 Change the timestamp associated with the current line by one day
9799 - {{{kbd(>)}}} (~org-agenda-date-prompt~) ::
9802 #+findex: org-agenda-date-prompt
9803 Change the timestamp associated with the current line. The key
9804 {{{kbd(>)}}} has been chosen, because it is the same as
9805 {{{kbd(S-.)}}} on my keyboard.
9807 - {{{kbd(I)}}} (~org-agenda-clock-in~) ::
9810 #+findex: org-agenda-clock-in
9811 Start the clock on the current item. If a clock is running already,
9812 it is stopped first.
9814 - {{{kbd(O)}}} (~org-agenda-clock-out~) ::
9817 #+findex: org-agenda-clock-out
9818 Stop the previously started clock.
9820 - {{{kbd(X)}}} (~org-agenda-clock-cancel~) ::
9823 #+findex: org-agenda-clock-cancel
9824 Cancel the currently running clock.
9826 - {{{kbd(J)}}} (~org-agenda-clock-goto~) ::
9829 #+findex: org-agenda-clock-goto
9830 Jump to the running clock in another window.
9832 - {{{kbd(k)}}} (~org-agenda-capture~) ::
9835 #+findex: org-agenda-capture
9836 #+cindex: capturing, from agenda
9837 #+vindex: org-capture-use-agenda-date
9838 Like ~org-capture~, but use the date at point as the default date
9839 for the capture template. See ~org-capture-use-agenda-date~ to make
9840 this the default behavior of ~org-capture~.
9842 *** Bulk remote editing selected entries
9846 #+cindex: remote editing, bulk, from agenda
9847 #+vindex: org-agenda-bulk-custom-functions
9849 - {{{kbd(m)}}} (~org-agenda-bulk-mark~) ::
9851 #+findex: org-agenda-bulk-mark
9853 Mark the entry at point for bulk action. If there is an active
9854 region in the agenda, mark the entries in the region. With numeric
9855 prefix argument, mark that many successive entries.
9857 - {{{kbd(*)}}} (~org-agenda-bulk-mark-all~) ::
9859 #+findex: org-agenda-bulk-mark-all
9861 Mark all visible agenda entries for bulk action.
9863 - {{{kbd(u)}}} (~org-agenda-bulk-unmark~) ::
9865 #+findex: org-agenda-bulk-unmark
9867 Unmark entry for bulk action.
9869 - {{{kbd(U)}}} (~org-agenda-bulk-remove-all-marks~) ::
9871 #+findex: org-agenda-bulk-remove-all-marks
9873 Unmark all marked entries for bulk action.
9875 - {{{kbd(M-m)}}} (~org-agenda-bulk-toggle~) ::
9877 #+findex: org-agenda-bulk-toggle
9879 Toggle mark of the entry at point for bulk action.
9881 - {{{kbd(M-*)}}} (~org-agenda-bulk-toggle-all~) ::
9883 #+findex: org-agenda-bulk-toggle-all
9885 Toggle mark of every entry for bulk action.
9887 - {{{kbd(%)}}} (~org-agenda-bulk-mark-regexp~) ::
9889 #+findex: org-agenda-bulk-mark-regexp
9891 Mark entries matching a regular expression for bulk action.
9893 - {{{kbd(B)}}} (~org-agenda-bulk-action~) ::
9895 #+findex: org-agenda-bulk-action
9896 #+vindex: org-agenda-bulk-persistent-marks
9898 Bulk action: act on all marked entries in the agenda. This prompts
9899 for another key to select the action to be applied. The prefix
9900 argument to {{{kbd(B)}}} is passed through to the {{{kbd(s)}}} and
9901 {{{kbd(d)}}} commands, to bulk-remove these special timestamps. By
9902 default, marks are removed after the bulk. If you want them to
9903 persist, set ~org-agenda-bulk-persistent-marks~ to ~t~ or hit
9904 {{{kbd(p)}}} at the prompt.
9908 Toggle persistent marks.
9912 Archive all selected entries.
9916 Archive entries by moving them to their respective archive
9921 Change TODO state. This prompts for a single TODO keyword and
9922 changes the state of all selected entries, bypassing blocking and
9923 suppressing logging notes---but not timestamps.
9927 Add a tag to all selected entries.
9931 Remove a tag from all selected entries.
9935 Schedule all items to a new date. To shift existing schedule
9936 dates by a fixed number of days, use something starting with
9937 double plus at the prompt, for example =++8d= or =++2w=.
9941 Set deadline to a specific date.
9945 Prompt for a single refile target and move all entries. The
9946 entries are no longer in the agenda; refresh ({{{kbd(g)}}}) to
9951 Reschedule randomly into the coming N days. N is prompted for.
9952 With a prefix argument ({{{kbd(C-u B S)}}}), scatter only across
9957 #+vindex: org-agenda-bulk-custom-functions
9958 Apply a function[fn:100] to marked entries. For example, the
9959 function below sets the =CATEGORY= property of the entries to
9962 #+begin_src emacs-lisp
9963 (defun set-category ()
9965 (let ((marker (or (org-get-at-bol 'org-hd-marker)
9966 (org-agenda-error))))
9967 (org-with-point-at marker
9968 (org-back-to-heading t)
9969 (org-set-property "CATEGORY" "web"))))
9972 *** Calendar commands
9976 #+cindex: calendar commands, from agenda
9978 - {{{kbd(c)}}} (~org-agenda-goto-calendar~) ::
9981 #+findex: org-agenda-goto-calendar
9982 Open the Emacs calendar and go to the date at point in the agenda.
9984 - {{{kbd(c)}}} (~org-calendar-goto-agenda~) ::
9987 #+findex: org-calendar-goto-agenda
9988 When in the calendar, compute and show the Org agenda for the date
9991 - {{{kbd(i)}}} (~org-agenda-diary-entry~) ::
9993 #+findex: org-agenda-diary-entry
9995 #+cindex: diary entries, creating from agenda
9996 Insert a new entry into the diary, using the date at point and (for
9997 block entries) the date at the mark. This adds to the Emacs diary
9998 file[fn:101], in a way similar to the {{{kbd(i)}}} command in the
9999 calendar. The diary file pops up in another window, where you can
10002 #+vindex: org-agenda-diary-file
10003 If you configure ~org-agenda-diary-file~ to point to an Org file,
10004 Org creates entries in that file instead. Most entries are stored
10005 in a date-based outline tree that will later make it easy to archive
10006 appointments from previous months/years. The tree is built under an
10007 entry with a =DATE_TREE= property, or else with years as top-level
10008 entries. Emacs prompts you for the entry text---if you specify it,
10009 the entry is created in ~org-agenda-diary-file~ without further
10010 interaction. If you directly press {{{kbd(RET)}}} at the prompt
10011 without typing text, the target file is shown in another window for
10012 you to finish the entry there. See also the {{{kbd(k r)}}} command.
10014 - {{{kbd(M)}}} (~org-agenda-phases-of-moon~) ::
10017 #+findex: org-agenda-phases-of-moon
10018 Show the phases of the moon for the three months around current
10021 - {{{kbd(S)}}} (~org-agenda-sunrise-sunset~) ::
10024 #+findex: org-agenda-sunrise-sunset
10025 Show sunrise and sunset times. The geographical location must be
10026 set with calendar variables, see the documentation for the Emacs
10029 - {{{kbd(C)}}} (~org-agenda-convert-date~) ::
10032 #+findex: org-agenda-convert-date
10033 Convert the date at point into many other cultural and historic
10036 - {{{kbd(H)}}} (~org-agenda-holidays~) ::
10039 #+findex: org-agenda-holidays
10040 Show holidays for three months around point date.
10047 - {{{kbd(q)}}} (~org-agenda-quit~) ::
10049 #+findex: org-agenda-quit
10051 Quit agenda, remove the agenda buffer.
10053 - {{{kbd(x)}}} (~org-agenda-exit~) ::
10055 #+findex: org-agenda-exit
10057 #+cindex: agenda files, removing buffers
10058 Exit agenda, remove the agenda buffer and all buffers loaded by
10059 Emacs for the compilation of the agenda. Buffers created by the
10060 user to visit Org files are not removed.
10062 ** Custom Agenda Views
10064 :DESCRIPTION: Defining special searches and views.
10066 #+cindex: custom agenda views
10067 #+cindex: agenda views, custom
10069 Custom agenda commands serve two purposes: to store and quickly access
10070 frequently used TODO and tags searches, and to create special
10071 composite agenda buffers. Custom agenda commands are accessible
10072 through the dispatcher (see [[*The Agenda Dispatcher]]), just like the
10075 *** Storing searches
10077 :DESCRIPTION: Type once, use often.
10080 The first application of custom searches is the definition of keyboard
10081 shortcuts for frequently used searches, either creating an agenda
10082 buffer, or a sparse tree (the latter covering of course only the
10085 #+kindex: C @r{(Agenda dispatcher)}
10086 #+vindex: org-agenda-custom-commands
10087 #+cindex: agenda views, main example
10088 #+cindex: agenda, as an agenda views
10089 #+cindex: agenda*, as an agenda views
10090 #+cindex: tags, as an agenda view
10091 #+cindex: todo, as an agenda view
10092 #+cindex: tags-todo
10093 #+cindex: todo-tree
10094 #+cindex: occur-tree
10095 #+cindex: tags-tree
10096 Custom commands are configured in the variable
10097 ~org-agenda-custom-commands~. You can customize this variable, for
10098 example by pressing {{{kbd(C)}}} from the agenda dispatcher (see [[*The
10099 Agenda Dispatcher]]). You can also directly set it with Emacs Lisp in
10100 the Emacs init file. The following example contains all valid agenda
10103 #+begin_src emacs-lisp
10104 (setq org-agenda-custom-commands
10107 ("w" todo "WAITING")
10108 ("W" todo-tree "WAITING")
10109 ("u" tags "+boss-urgent")
10110 ("v" tags-todo "+boss-urgent")
10111 ("U" tags-tree "+boss-urgent")
10112 ("f" occur-tree "\\<FIXME\\>")
10113 ("h" . "HOME+Name tags searches") ;description for "h" prefix
10114 ("hl" tags "+home+Lisa")
10115 ("hp" tags "+home+Peter")
10116 ("hk" tags "+home+Kim")))
10119 #+texinfo: @noindent
10120 The initial string in each entry defines the keys you have to press
10121 after the dispatcher command in order to access the command. Usually
10122 this will be just a single character, but if you have many similar
10123 commands, you can also define two-letter combinations where the first
10124 character is the same in several combinations and serves as a prefix
10125 key[fn:102]. The second parameter is the search type, followed by the
10126 string or regular expression to be used for the matching. The example
10127 above will therefore define:
10131 as a global search for agenda entries planned[fn:103] this week/day.
10135 as the same search, but only for entries with an hour specification
10136 like =[h]h:mm=---think of them as appointments.
10140 as a global search for TODO entries with =WAITING= as the TODO
10145 as the same search, but only in the current buffer and displaying
10146 the results as a sparse tree.
10150 as a global tags search for headlines tagged =boss= but not
10155 The same search, but limiting it to headlines that are also TODO
10160 as the same search, but only in the current buffer and displaying
10161 the result as a sparse tree.
10165 to create a sparse tree (again, current buffer only) with all
10166 entries containing the word =FIXME=.
10170 as a prefix command for a =HOME= tags search where you have to press
10171 an additional key ({{{kbd(l)}}}, {{{kbd(p)}}} or {{{kbd(k)}}}) to
10172 select a name (Lisa, Peter, or Kim) as additional tag to match.
10174 Note that ~*-tree~ agenda views need to be called from an Org buffer
10175 as they operate on the current buffer only.
10179 :DESCRIPTION: All the stuff you need in a single buffer.
10181 #+cindex: block agenda
10182 #+cindex: agenda, with block views
10184 Another possibility is the construction of agenda views that comprise
10185 the results of /several/ commands, each of which creates a block in
10186 the agenda buffer. The available commands include ~agenda~ for the
10187 daily or weekly agenda (as created with {{{kbd(a)}}}) , ~alltodo~ for
10188 the global TODO list (as constructed with {{{kbd(t)}}}), and the
10189 matching commands discussed above: ~todo~, ~tags~, and ~tags-todo~.
10190 Here are two examples:
10192 #+begin_src emacs-lisp
10193 (setq org-agenda-custom-commands
10194 '(("h" "Agenda and Home-related tasks"
10198 ("o" "Agenda and Office-related tasks"
10201 (tags "office")))))
10204 #+texinfo: @noindent
10205 This defines {{{kbd(h)}}} to create a multi-block view for stuff you
10206 need to attend to at home. The resulting agenda buffer contains your
10207 agenda for the current week, all TODO items that carry the tag =home=,
10208 and also all lines tagged with =garden=. Finally the command
10209 {{{kbd(o)}}} provides a similar view for office tasks.
10211 *** Setting options for custom commands
10213 :DESCRIPTION: Changing the rules.
10214 :ALT_TITLE: Setting options
10216 #+cindex: options, for custom agenda views
10218 #+vindex: org-agenda-custom-commands
10219 Org mode contains a number of variables regulating agenda construction
10220 and display. The global variables define the behavior for all agenda
10221 commands, including the custom commands. However, if you want to
10222 change some settings just for a single custom view, you can do so.
10223 Setting options requires inserting a list of variable names and values
10224 at the right spot in ~org-agenda-custom-commands~. For example:
10226 #+begin_src emacs-lisp
10227 (setq org-agenda-custom-commands
10228 '(("w" todo "WAITING"
10229 ((org-agenda-sorting-strategy '(priority-down))
10230 (org-agenda-prefix-format " Mixed: ")))
10231 ("U" tags-tree "+boss-urgent"
10232 ((org-show-context-detail 'minimal)))
10234 ((org-agenda-files '("~org/notes.org"))
10235 (org-agenda-text-search-extra-files nil)))))
10238 #+texinfo: @noindent
10239 Now the {{{kbd(w)}}} command sorts the collected entries only by
10240 priority, and the prefix format is modified to just say =Mixed:=
10241 instead of giving the category of the entry. The sparse tags tree of
10242 {{{kbd(U)}}} now turns out ultra-compact, because neither the headline
10243 hierarchy above the match, nor the headline following the match are
10244 shown. The command {{{kbd(N)}}} does a text search limited to only
10247 For command sets creating a block agenda, ~org-agenda-custom-commands~
10248 has two separate spots for setting options. You can add options that
10249 should be valid for just a single command in the set, and options that
10250 should be valid for all commands in the set. The former are just
10251 added to the command entry; the latter must come after the list of
10252 command entries. Going back to the block agenda example (see [[*Block
10253 agenda]]), let's change the sorting strategy for the {{{kbd(h)}}}
10254 commands to ~priority-down~, but let's sort the results for =garden=
10255 tags query in the opposite order, ~priority-up~. This would look like
10258 #+begin_src emacs-lisp
10259 (setq org-agenda-custom-commands
10260 '(("h" "Agenda and Home-related tasks"
10264 ((org-agenda-sorting-strategy '(priority-up)))))
10265 ((org-agenda-sorting-strategy '(priority-down))))
10266 ("o" "Agenda and Office-related tasks"
10269 (tags "office")))))
10272 As you see, the values and parentheses setting is a little complex.
10273 When in doubt, use the customize interface to set this variable---it
10274 fully supports its structure. Just one caveat: when setting options
10275 in this interface, the /values/ are just Lisp expressions. So if the
10276 value is a string, you need to add the double-quotes around the value
10279 #+vindex: org-agenda-custom-commands-contexts
10280 To control whether an agenda command should be accessible from
10281 a specific context, you can customize
10282 ~org-agenda-custom-commands-contexts~. Let's say for example that you
10283 have an agenda command {{{kbd(o)}}} displaying a view that you only
10284 need when reading emails. Then you would configure this option like
10287 #+begin_src emacs-lisp
10288 (setq org-agenda-custom-commands-contexts
10289 '(("o" (in-mode . "message-mode"))))
10292 You can also tell that the command key {{{kbd(o)}}} should refer to
10293 another command key {{{kbd(r)}}}. In that case, add this command key
10296 #+begin_src emacs-lisp
10297 (setq org-agenda-custom-commands-contexts
10298 '(("o" "r" (in-mode . "message-mode"))))
10301 See the docstring of the variable for more information.
10303 ** Exporting Agenda Views
10305 :DESCRIPTION: Writing a view to a file.
10307 #+cindex: agenda views, exporting
10309 If you are away from your computer, it can be very useful to have
10310 a printed version of some agenda views to carry around. Org mode can
10311 export custom agenda views as plain text, HTML[fn:104], Postscript,
10312 PDF[fn:105], and iCalendar files. If you want to do this only
10313 occasionally, use the following command:
10315 - {{{kbd(C-x C-w)}}} (~org-agenda-write~) ::
10317 #+findex: org-agenda-write
10318 #+cindex: exporting agenda views
10319 #+cindex: agenda views, exporting
10321 #+vindex: org-agenda-exporter-settings
10322 Write the agenda view to a file.
10324 If you need to export certain agenda views frequently, you can
10325 associate any custom agenda command with a list of output file
10326 names[fn:106]. Here is an example that first defines custom commands
10327 for the agenda and the global TODO list, together with a number of
10328 files to which to export them. Then we define two block agenda
10329 commands and specify file names for them as well. File names can be
10330 relative to the current working directory, or absolute.
10332 #+begin_src emacs-lisp
10333 (setq org-agenda-custom-commands
10334 '(("X" agenda "" nil ("agenda.html" "agenda.ps"))
10335 ("Y" alltodo "" nil ("todo.html" "todo.txt" "todo.ps"))
10336 ("h" "Agenda and Home-related tasks"
10341 ("~/views/home.html"))
10342 ("o" "Agenda and Office-related tasks"
10347 ("~/views/office.ps" "~/calendars/office.ics"))))
10350 The extension of the file name determines the type of export. If it
10351 is =.html=, Org mode uses the htmlize package to convert the buffer to
10352 HTML and save it to this file name. If the extension is =.ps=,
10353 ~ps-print-buffer-with-faces~ is used to produce Postscript output. If
10354 the extension is =.ics=, iCalendar export is run export over all files
10355 that were used to construct the agenda, and limit the export to
10356 entries listed in the agenda. Any other extension produces a plain
10359 The export files are /not/ created when you use one of those
10360 commands interactively because this might use too much overhead.
10361 Instead, there is a special command to produce /all/ specified
10364 - {{{kbd(e)}}} (~org-store-agenda-views~) ::
10366 #+kindex: e @r{(Agenda dispatcher)}
10367 #+findex: org-store-agenda-views
10368 Export all agenda views that have export file names associated with
10371 You can use the options section of the custom agenda commands to also
10372 set options for the export commands. For example:
10374 #+begin_src emacs-lisp
10375 (setq org-agenda-custom-commands
10377 ((ps-number-of-columns 2)
10378 (ps-landscape-mode t)
10379 (org-agenda-prefix-format " [ ] ")
10380 (org-agenda-with-colors nil)
10381 (org-agenda-remove-tags t))
10382 ("theagenda.ps"))))
10385 #+texinfo: @noindent
10386 #+vindex: org-agenda-exporter-settings
10387 This command sets two options for the Postscript exporter, to make it
10388 print in two columns in landscape format---the resulting page can be
10389 cut in two and then used in a paper agenda. The remaining settings
10390 modify the agenda prefix to omit category and scheduling information,
10391 and instead include a checkbox to check off items. We also remove the
10392 tags to make the lines compact, and we do not want to use colors for
10393 the black-and-white printer. Settings specified in
10394 ~org-agenda-exporter-settings~ also apply, e.g.,
10396 #+begin_src emacs-lisp
10397 (setq org-agenda-exporter-settings
10398 '((ps-number-of-columns 2)
10399 (ps-landscape-mode t)
10400 (org-agenda-add-entry-text-maxlines 5)
10401 (htmlize-output-type 'css)))
10404 #+texinfo: @noindent
10405 but the settings in ~org-agenda-custom-commands~ take precedence.
10407 From the command line you may also use:
10410 emacs -eval (org-batch-store-agenda-views) -kill
10413 #+texinfo: @noindent
10414 or, if you need to modify some parameters[fn:107]
10417 emacs -eval '(org-batch-store-agenda-views \
10418 org-agenda-span (quote month) \
10419 org-agenda-start-day "2007-11-01" \
10420 org-agenda-include-diary nil \
10421 org-agenda-files (quote ("~/org/project.org")))' \
10425 #+texinfo: @noindent
10426 which creates the agenda views restricted to the file
10427 =~/org/project.org=, without diary entries and with a 30-day extent.
10429 You can also extract agenda information in a way that allows further
10430 processing by other programs. See [[*Extracting Agenda Information]], for
10433 ** Using Column View in the Agenda
10435 :DESCRIPTION: Using column view for collected entries.
10436 :ALT_TITLE: Agenda Column View
10438 #+cindex: column view, in agenda
10439 #+cindex: agenda, column view
10441 Column view (see [[*Column View]]) is normally used to view and edit
10442 properties embedded in the hierarchical structure of an Org file. It
10443 can be quite useful to use column view also from the agenda, where
10444 entries are collected by certain criteria.
10446 - {{{kbd(C-c C-x C-c)}}} (~org-agenda-columns~) ::
10447 #+kindex: C-c C-x C-c
10448 #+findex: org-agenda-columns
10450 Turn on column view in the agenda.
10452 To understand how to use this properly, it is important to realize
10453 that the entries in the agenda are no longer in their proper outline
10454 environment. This causes the following issues:
10457 #+vindex: org-columns-default-format
10458 #+vindex: org-overriding-columns-format
10459 Org needs to make a decision which columns format to use. Since
10460 the entries in the agenda are collected from different files, and
10461 different files may have different columns formats, this is
10462 a non-trivial problem. Org first checks if the variable
10463 ~org-overriding-columns-format~ is currently set, and if so, takes
10464 the format from there. Otherwise it takes the format associated
10465 with the first item in the agenda, or, if that item does not have
10466 a specific format (defined in a property, or in its file), it uses
10467 ~org-columns-default-format~.
10470 #+cindex: @samp{CLOCKSUM}, special property
10471 If any of the columns has a summary type defined (see [[*Column
10472 attributes]]), turning on column view in the agenda visits all
10473 relevant agenda files and make sure that the computations of this
10474 property are up to date. This is also true for the special
10475 =CLOCKSUM= property. Org then sums the values displayed in the
10476 agenda. In the daily/weekly agenda, the sums cover a single day;
10477 in all other views they cover the entire block.
10479 It is important to realize that the agenda may show the same entry
10480 /twice/---for example as scheduled and as a deadline---and it may
10481 show two entries from the same hierarchy (for example a /parent/
10482 and its /child/). In these cases, the summation in the agenda
10483 leads to incorrect results because some values count double.
10485 3. When the column view in the agenda shows the =CLOCKSUM= property,
10486 that is always the entire clocked time for this item. So even in
10487 the daily/weekly agenda, the clocksum listed in column view may
10488 originate from times outside the current view. This has the
10489 advantage that you can compare these values with a column listing
10490 the planned total effort for a task---one of the major
10491 applications for column view in the agenda. If you want
10492 information about clocked time in the displayed period use clock
10493 table mode (press {{{kbd(R)}}} in the agenda).
10496 #+cindex: @samp{CLOCKSUM_T}, special property
10497 When the column view in the agenda shows the =CLOCKSUM_T= property,
10498 that is always today's clocked time for this item. So even in the
10499 weekly agenda, the clocksum listed in column view only originates
10500 from today. This lets you compare the time you spent on a task for
10501 today, with the time already spent---via =CLOCKSUM=---and with
10502 the planned total effort for it.
10504 * Markup for Rich Contents
10506 :DESCRIPTION: Compose beautiful documents.
10509 Org is primarily about organizing and searching through your
10510 plain-text notes. However, it also provides a lightweight yet robust
10511 markup language for rich text formatting and more. For instance, you
10512 may want to center or emphasize text. Or you may need to insert
10513 a formula or image in your writing. Org offers syntax for all of this
10514 and more. Used in conjunction with the export framework (see
10515 [[*Exporting]]), you can author beautiful documents in Org---like the fine
10516 manual you are currently reading.
10520 :DESCRIPTION: The basic unit of text.
10523 #+cindex: paragraphs, markup rules
10524 Paragraphs are separated by at least one empty line. If you need to
10525 enforce a line break within a paragraph, use =\\= at the end of
10528 #+cindex: line breaks, markup rules
10529 To preserve the line breaks, indentation and blank lines in a region,
10530 but otherwise use normal formatting, you can use this construct, which
10531 can also be used to format poetry.
10533 #+cindex: @samp{BEGIN_VERSE}
10534 #+cindex: verse blocks
10537 Great clouds overhead
10538 Tiny black birds rise and fall
10545 When quoting a passage from another document, it is customary to
10546 format this as a paragraph that is indented on both the left and the
10547 right margin. You can include quotations in Org documents like this:
10549 #+cindex: @samp{BEGIN_QUOTE}
10550 #+cindex: quote blocks
10553 Everything should be made as simple as possible,
10554 but not any simpler ---Albert Einstein
10558 If you would like to center some text, do it like this:
10560 #+cindex: @samp{BEGIN_CENTER}
10561 #+cindex: center blocks
10564 Everything should be made as simple as possible, \\
10565 but not any simpler
10569 ** Emphasis and Monospace
10571 :DESCRIPTION: Bold, italic, etc.
10573 #+cindex: underlined text, markup rules
10574 #+cindex: bold text, markup rules
10575 #+cindex: italic text, markup rules
10576 #+cindex: verbatim text, markup rules
10577 #+cindex: code text, markup rules
10578 #+cindex: strike-through text, markup rules
10580 You can make words =*bold*=, =/italic/=, =_underlined_=, ==verbatim==
10581 and =~code~=, and, if you must, =+strike-through+=. Text in the code
10582 and verbatim string is not processed for Org mode specific syntax; it
10583 is exported verbatim.
10585 #+vindex: org-fontify-emphasized-text
10586 To turn off fontification for marked up text, you can set
10587 ~org-fontify-emphasized-text~ to ~nil~. To narrow down the list of
10588 available markup syntax, you can customize ~org-emphasis-alist~.
10590 ** Subscripts and Superscripts
10592 :DESCRIPTION: Simple syntax for raising/lowering text.
10594 #+cindex: subscript
10595 #+cindex: superscript
10597 =^= and =_= are used to indicate super- and subscripts. To increase
10598 the readability of ASCII text, it is not necessary, but OK, to
10599 surround multi-character sub- and superscripts with curly braces. For
10603 The radius of the sun is R_sun = 6.96 x 10^8 m. On the other hand,
10604 the radius of Alpha Centauri is R_{Alpha Centauri} = 1.28 x R_{sun}.
10607 #+vindex: org-use-sub-superscripts
10608 If you write a text where the underscore is often used in a different
10609 context, Org's convention to always interpret these as subscripts can
10610 get in your way. Configure the variable ~org-use-sub-superscripts~ to
10611 change this convention. For example, when setting this variable to
10612 ~{}~, =a_b= is not interpreted as a subscript, but =a_{b}= is.
10614 - {{{kbd(C-c C-x \)}}} (~org-toggle-pretty-entities~) ::
10616 #+kindex: C-c C-x \
10617 #+findex: org-toggle-pretty-entities
10618 This command formats sub- and superscripts in a WYSIWYM way.
10622 :DESCRIPTION: Greek letters and other symbols.
10624 #+cindex: math symbols
10625 #+cindex: special symbols
10628 You can use LaTeX-like syntax to insert special symbols---named
10629 entities---like =\alpha= to indicate the Greek letter, or =\to= to indicate
10630 an arrow. Completion for these symbols is available, just type =\=
10631 and maybe a few letters, and press {{{kbd(M-TAB)}}} to see possible
10632 completions. If you need such a symbol inside a word, terminate it
10633 with a pair of curly brackets. For example
10636 Pro tip: Given a circle \Gamma of diameter d, the length of its
10637 circumference is \pi{}d.
10640 #+findex: org-entities-help
10641 #+vindex: org-entities-user
10642 A large number of entities is provided, with names taken from both
10643 HTML and LaTeX; you can comfortably browse the complete list from
10644 a dedicated buffer using the command ~org-entities-help~. It is also
10645 possible to provide your own special symbols in the variable
10646 ~org-entities-user~.
10648 During export, these symbols are transformed into the native format of
10649 the exporter back-end. Strings like =\alpha= are exported as =α= in
10650 the HTML output, and as =\(\alpha\)= in the LaTeX output. Similarly, =\nbsp=
10651 becomes = = in HTML and =~= in LaTeX.
10653 #+cindex: special symbols, in-buffer display
10654 If you would like to see entities displayed as UTF-8 characters, use
10655 the following command[fn:108]:
10657 - {{{kbd(C-c C-x \)}}} (~org-toggle-pretty-entities~) ::
10658 #+kindex: C-c C-x \
10659 #+findex: org-toggle-pretty-entities
10661 Toggle display of entities as UTF-8 characters. This does not
10662 change the buffer content which remains plain ASCII, but it overlays
10663 the UTF-8 character for display purposes only.
10665 #+cindex: shy hyphen, special symbol
10666 #+cindex: dash, special symbol
10667 #+cindex: ellipsis, special symbol
10668 In addition to regular entities defined above, Org exports in
10669 a special way[fn:109] the following commonly used character
10670 combinations: =\-= is treated as a shy hyphen, =--= and =---= are
10671 converted into dashes, and =...= becomes a compact set of dots.
10675 :DESCRIPTION: LaTeX can be freely used inside Org documents.
10677 #+cindex: @TeX{} interpretation
10678 #+cindex: @LaTeX{} interpretation
10680 Plain ASCII is normally sufficient for almost all note taking.
10681 Exceptions include scientific notes, which often require mathematical
10682 symbols and the occasional formula. LaTeX[fn:110] is widely used to
10683 typeset scientific documents. Org mode supports embedding LaTeX code
10684 into its files, because many academics are used to writing and reading
10685 LaTeX source code, and because it can be readily processed to produce
10686 pretty output for a number of export back-ends.
10688 *** LaTeX fragments
10690 :DESCRIPTION: Complex formulas made easy.
10692 #+cindex: @LaTeX{} fragments
10694 #+vindex: org-format-latex-header
10695 Org mode can contain LaTeX math fragments, and it supports ways to
10696 process these for several export back-ends. When exporting to LaTeX,
10697 the code is left as it is. When exporting to HTML, Org can use either
10698 [[http://www.mathjax.org][MathJax]] (see [[*Math formatting in HTML export]]) or transcode the math
10699 into images (see [[*Previewing LaTeX fragments]]).
10701 LaTeX fragments do not need any special marking at all. The following
10702 snippets are identified as LaTeX source code:
10704 - Environments of any kind[fn:111]. The only requirement is that the
10705 =\begin= statement appears on a new line, preceded by only
10708 - Text within the usual LaTeX math delimiters. To avoid conflicts
10709 with currency specifications, single =$= characters are only
10710 recognized as math delimiters if the enclosed text contains at most
10711 two line breaks, is directly attached to the =$= characters with no
10712 whitespace in between, and if the closing =$= is followed by
10713 whitespace, punctuation or a dash. For the other delimiters, there
10714 is no such restriction, so when in doubt, use =\(...\)= as inline
10717 #+texinfo: @noindent
10721 \begin{equation} % arbitrary environments,
10722 x=\sqrt{b} % even tables, figures
10723 \end{equation} % etc
10725 If $a^2=b$ and \( b=2 \), then the solution must be
10726 either $$ a=+\sqrt{2} $$ or \[ a=-\sqrt{2} \].
10729 #+vindex: org-export-with-latex
10730 LaTeX processing can be configured with the variable
10731 ~org-export-with-latex~. The default setting is ~t~ which means
10732 MathJax for HTML, and no processing for ASCII and LaTeX back-ends.
10733 You can also set this variable on a per-file basis using one of these
10736 | =#+OPTIONS: tex:t= | Do the right thing automatically (MathJax) |
10737 | =#+OPTIONS: tex:nil= | Do not process LaTeX fragments at all |
10738 | =#+OPTIONS: tex:verbatim= | Verbatim export, for jsMath or so |
10740 *** Previewing LaTeX fragments
10742 :DESCRIPTION: What will this snippet look like?
10744 #+cindex: @LaTeX{} fragments, preview
10746 #+vindex: org-preview-latex-default-process
10747 If you have a working LaTeX installation and =dvipng=, =dvisvgm= or
10748 =convert= installed[fn:112], LaTeX fragments can be processed to
10749 produce images of the typeset expressions to be used for inclusion
10750 while exporting to HTML (see [[*LaTeX fragments]]), or for inline
10751 previewing within Org mode.
10753 #+vindex: org-format-latex-options
10754 #+vindex: org-format-latex-header
10755 You can customize the variables ~org-format-latex-options~ and
10756 ~org-format-latex-header~ to influence some aspects of the preview.
10757 In particular, the ~:scale~ (and for HTML export, ~:html-scale~)
10758 property of the former can be used to adjust the size of the preview
10761 - {{{kbd(C-c C-x C-l)}}} (~org-latex-preview~) ::
10762 #+kindex: C-c C-x C-l
10763 #+findex: org-latex-preview
10765 Produce a preview image of the LaTeX fragment at point and overlay
10766 it over the source code. If there is no fragment at point, process
10767 all fragments in the current entry---between two headlines.
10769 When called with a single prefix argument, clear all images in the
10770 current entry. Two prefix arguments produce a preview image for all
10771 fragments in the buffer, while three of them clear all the images in
10774 #+vindex: org-startup-with-latex-preview
10775 You can turn on the previewing of all LaTeX fragments in a file with
10777 : #+STARTUP: latexpreview
10779 To disable it, simply use
10781 : #+STARTUP: nolatexpreview
10783 *** Using CDLaTeX to enter math
10785 :DESCRIPTION: Speed up entering of formulas.
10786 :ALT_TITLE: CDLaTeX mode
10788 #+cindex: CD@LaTeX{}
10790 CDLaTeX mode is a minor mode that is normally used in combination with
10791 a major LaTeX mode like AUCTeX in order to speed-up insertion of
10792 environments and math templates. Inside Org mode, you can make use of
10793 some of the features of CDLaTeX mode. You need to install
10794 =cdlatex.el= and =texmathp.el= (the latter comes also with AUCTeX)
10795 from [[http://www.astro.uva.nl/~dominik/Tools/cdlatex]]. Do not use
10796 CDLaTeX mode itself under Org mode, but use the light version
10797 ~org-cdlatex-mode~ that comes as part of Org mode. Turn it on for the
10798 current buffer with {{{kbd(M-x org-cdlatex-mode)}}}, or for all Org
10801 #+begin_src emacs-lisp
10802 (add-hook 'org-mode-hook 'turn-on-org-cdlatex)
10805 When this mode is enabled, the following features are present (for
10806 more details see the documentation of CDLaTeX mode):
10808 #+attr_texinfo: :sep ,
10809 - {{{kbd(C-c {)}}} ::
10812 Insert an environment template.
10814 - {{{kbd(TAB)}}} ::
10817 The {{{kbd(TAB)}}} key expands the template if point is inside
10818 a LaTeX fragment[fn:113]. For example, {{{kbd(TAB)}}} expands =fr=
10819 to =\frac{}{}= and position point correctly inside the first brace.
10820 Another {{{kbd(TAB)}}} gets you into the second brace.
10822 Even outside fragments, {{{kbd(TAB)}}} expands environment
10823 abbreviations at the beginning of a line. For example, if you write
10824 =equ= at the beginning of a line and press {{{kbd(TAB)}}}, this
10825 abbreviation is expanded to an =equation= environment. To get
10826 a list of all abbreviations, type {{{kbd(M-x
10827 cdlatex-command-help)}}}.
10829 - {{{kbd(^)}}}, {{{kbd(_)}}} ::
10832 #+vindex: cdlatex-simplify-sub-super-scripts
10834 Pressing {{{kbd(_)}}} and {{{kbd(^)}}} inside a LaTeX fragment
10835 inserts these characters together with a pair of braces. If you use
10836 {{{kbd(TAB)}}} to move out of the braces, and if the braces surround
10837 only a single character or macro, they are removed again (depending
10838 on the variable ~cdlatex-simplify-sub-super-scripts~).
10843 Pressing the backquote followed by a character inserts math macros,
10844 also outside LaTeX fragments. If you wait more than 1.5 seconds
10845 after the backquote, a help window pops up.
10850 Pressing the single-quote followed by another character modifies the
10851 symbol before point with an accent or a font. If you wait more than
10852 1.5 seconds after the single-quote, a help window pops up.
10853 Character modification works only inside LaTeX fragments; outside
10854 the quote is normal.
10856 ** Literal Examples
10858 :DESCRIPTION: Source code examples with special formatting.
10860 #+cindex: literal examples, markup rules
10861 #+cindex: code line references, markup rules
10863 You can include literal examples that should not be subjected to
10864 markup. Such examples are typeset in monospace, so this is well
10865 suited for source code and similar examples.
10867 #+cindex: @samp{BEGIN_EXAMPLE}
10868 #+cindex: example block
10871 Some example from a text file.
10875 Note that such blocks may be /indented/ in order to align nicely with
10876 indented text and in particular with plain list structure (see
10877 [[*Plain Lists]]). For simplicity when using small examples, you can
10878 also start the example lines with a colon followed by a space. There
10879 may also be additional whitespace before the colon:
10883 : Some example from a text file.
10886 #+cindex: formatting source code, markup rules
10887 #+vindex: org-latex-listings
10888 If the example is source code from a programming language, or any
10889 other text that can be marked up by Font Lock in Emacs, you can ask
10890 for the example to look like the fontified Emacs buffer[fn:114]. This
10891 is done with the code block, where you also need to specify the name
10892 of the major mode that should be used to fontify the example[fn:115],
10893 see [[*Structure Templates]] for shortcuts to easily insert code blocks.
10895 #+cindex: @samp{BEGIN_SRC}
10896 #+cindex: source block
10898 ,#+BEGIN_SRC emacs-lisp
10899 (defun org-xor (a b)
10905 Both in =example= and in =src= snippets, you can add a =-n= switch to
10906 the end of the =#+BEGIN= line, to get the lines of the example
10907 numbered. The =-n= takes an optional numeric argument specifying the
10908 starting line number of the block. If you use a =+n= switch, the
10909 numbering from the previous numbered snippet is continued in the
10910 current one. The =+n= switch can also take a numeric argument. This
10911 adds the value of the argument to the last line of the previous block
10912 to determine the starting line number.
10915 ,#+BEGIN_SRC emacs-lisp -n 20
10916 ;; This exports with line number 20.
10917 (message "This is line 21")
10920 ,#+BEGIN_SRC emacs-lisp +n 10
10921 ;; This is listed as line 31.
10922 (message "This is line 32")
10926 In literal examples, Org interprets strings like =(ref:name)= as
10927 labels, and use them as targets for special hyperlinks like
10928 =[[(name)]]=---i.e., the reference name enclosed in single parenthesis.
10929 In HTML, hovering the mouse over such a link remote-highlights the
10930 corresponding code line, which is kind of cool.
10932 You can also add a =-r= switch which /removes/ the labels from the
10933 source code[fn:116]. With the =-n= switch, links to these references
10934 are labeled by the line numbers from the code listing. Otherwise
10935 links use the labels with no parentheses. Here is an example:
10937 #+begin_example -l "(dumb-reference:%s)"
10938 ,#+BEGIN_SRC emacs-lisp -n -r
10939 (save-excursion (ref:sc)
10940 (goto-char (point-min)) (ref:jump)
10942 In line [[(sc)]] we remember the current position. [[(jump)][Line (jump)]]
10943 jumps to point-min.
10946 #+cindex: indentation, in source blocks
10947 Finally, you can use =-i= to preserve the indentation of a specific
10948 code block (see [[*Editing Source Code]]).
10950 #+vindex: org-coderef-label-format
10951 If the syntax for the label format conflicts with the language syntax,
10952 use a =-l= switch to change the format, for example
10954 : #+BEGIN_SRC pascal -n -r -l "((%s))"
10956 #+texinfo: @noindent
10957 See also the variable ~org-coderef-label-format~.
10959 HTML export also allows examples to be published as text areas (see
10960 [[*Text areas in HTML export]]).
10962 Because the =#+BEGIN= ... =#+END= patterns need to be added so often,
10963 a shortcut is provided (see [[*Structure Templates]]).
10965 - {{{kbd(C-c ')}}} (~org-edit-special~) ::
10968 #+findex: org-edit-special
10969 Edit the source code example at point in its native mode. This
10970 works by switching to a temporary buffer with the source code. You
10971 need to exit by pressing {{{kbd(C-c ')}}} again[fn:117]. The edited
10972 version then replaces the old version in the Org buffer.
10973 Fixed-width regions---where each line starts with a colon followed
10974 by a space---are edited using ~artist-mode~[fn:118] to allow
10975 creating ASCII drawings easily. Using this command in an empty line
10976 creates a new fixed-width region.
10978 #+cindex: storing link, in a source code buffer
10979 Calling ~org-store-link~ (see [[*Handling Links]]) while editing a source
10980 code example in a temporary buffer created with {{{kbd(C-c ')}}}
10981 prompts for a label. Make sure that it is unique in the current
10982 buffer, and insert it with the proper formatting like =(ref:label)= at
10983 the end of the current line. Then the label is stored as a link
10984 =(label)=, for retrieval with {{{kbd(C-c C-l)}}}.
10988 :DESCRIPTION: Display an image.
10991 #+cindex: inlining images
10992 #+cindex: images, markup rules
10993 An image is a link to an image file[fn:119] that does not have
10994 a description part, for example
10998 If you wish to define a caption for the image (see [[*Captions]]) and
10999 maybe a label for internal cross references (see [[*Internal Links]]),
11000 make sure that the link is on a line by itself and precede it with
11001 =CAPTION= and =NAME= keywords as follows:
11004 ,#+CAPTION: This is the caption for the next figure link (or table)
11005 ,#+NAME: fig:SED-HR4049
11009 #+texinfo: @noindent
11010 Such images can be displayed within the buffer with the following
11013 - {{{kbd(C-c C-x C-v)}}} (~org-toggle-inline-images~) ::
11015 #+kindex: C-c C-x C-v
11016 #+findex: org-toggle-inline-images
11017 #+vindex: org-startup-with-inline-images
11018 Toggle the inline display of linked images. When called with
11019 a prefix argument, also display images that do have a link
11020 description. You can ask for inline images to be displayed at
11021 startup by configuring the variable
11022 ~org-startup-with-inline-images~[fn:120].
11026 :DESCRIPTION: Describe tables, images...
11028 #+cindex: captions, markup rules
11029 #+cindex: @samp{CAPTION}, keyword
11031 You can assign a caption to a specific part of a document by inserting
11032 a =CAPTION= keyword immediately before it:
11035 ,#+CAPTION: This is the caption for the next table (or link)
11040 Optionally, the caption can take the form:
11042 : #+CAPTION[Short caption]: Longer caption.
11044 Even though images and tables are prominent examples of captioned
11045 structures, the same caption mechanism can apply to many
11046 others---e.g., LaTeX equations, source code blocks. Depending on the
11047 export back-end, those may or may not be handled.
11049 ** Horizontal Rules
11051 :DESCRIPTION: Make a line.
11054 #+cindex: horizontal rules, markup rules
11055 A line consisting of only dashes, and at least 5 of them, is exported
11056 as a horizontal line.
11060 :DESCRIPTION: Sharing and publishing notes.
11062 #+cindex: exporting
11064 At some point you might want to print your notes, publish them on the
11065 web, or share them with people not using Org. Org can convert and
11066 export documents to a variety of other formats while retaining as much
11067 structure (see [[*Document Structure]]) and markup (see [[*Markup for Rich
11068 Contents]]) as possible.
11070 #+cindex: export back-end
11071 The libraries responsible for translating Org files to other formats
11072 are called /back-ends/. Org ships with support for the following
11075 - /ascii/ (ASCII format)
11076 - /beamer/ (LaTeX Beamer format)
11077 - /html/ (HTML format)
11078 - /icalendar/ (iCalendar format)
11079 - /latex/ (LaTeX format)
11080 - /md/ (Markdown format)
11081 - /odt/ (OpenDocument Text format)
11082 - /org/ (Org format)
11083 - /texinfo/ (Texinfo format)
11084 - /man/ (Man page format)
11086 Users can install libraries for additional formats from the Emacs
11087 packaging system. For easy discovery, these packages have a common
11088 naming scheme: ~ox-NAME~, where {{{var(NAME)}}} is a format. For
11089 example, ~ox-koma-letter~ for /koma-letter/ back-end. More libraries
11090 can be found in the =contrib/= directory (see [[*Installation]]).
11092 #+vindex: org-export-backends
11093 Org only loads back-ends for the following formats by default: ASCII,
11094 HTML, iCalendar, LaTeX, and ODT. Additional back-ends can be loaded
11095 in either of two ways: by configuring the ~org-export-backends~
11096 variable, or by requiring libraries in the Emacs init file. For
11097 example, to load the Markdown back-end, add this to your Emacs config:
11099 #+begin_src emacs-lisp
11103 ** The Export Dispatcher
11105 :DESCRIPTION: The main interface.
11107 #+cindex: dispatcher, for export commands
11108 #+cindex: export, dispatcher
11110 The export dispatcher is the main interface for Org's exports.
11111 A hierarchical menu presents the currently configured export formats.
11112 Options are shown as easy toggle switches on the same screen.
11114 #+vindex: org-export-dispatch-use-expert-ui
11115 Org also has a minimal prompt interface for the export dispatcher.
11116 When the variable ~org-export-dispatch-use-expert-ui~ is set to
11117 a non-~nil~ value, Org prompts in the minibuffer. To switch back to
11118 the hierarchical menu, press {{{kbd(?)}}}.
11120 - {{{kbd(C-c C-e)}}} (~org-export~) ::
11122 #+findex: org-export
11124 Invokes the export dispatcher interface. The options show default
11125 settings. The {{{kbd(C-u)}}} prefix argument preserves options from
11126 the previous export, including any sub-tree selections.
11128 Org exports the entire buffer by default. If the Org buffer has an
11129 active region, then Org exports just that region.
11131 Within the dispatcher interface, the following key combinations can
11132 further alter what is exported, and how.
11134 - {{{kbd(C-a)}}} ::
11135 #+kindex: C-c C-e C-a
11137 Toggle asynchronous export. Asynchronous export uses an external
11138 Emacs process with a specially configured initialization file to
11139 complete the exporting process in the background, without tying-up
11140 Emacs. This is particularly useful when exporting long documents.
11142 Output from an asynchronous export is saved on the /export stack/.
11143 To view this stack, call the export dispatcher with a double
11144 {{{kbd(C-u)}}} prefix argument. If already in the export dispatcher
11145 menu, {{{kbd(&)}}} displays the stack.
11147 #+vindex: org-export-in-background
11148 You can make asynchronous export the default by setting
11149 ~org-export-in-background~.
11151 #+vindex: org-export-async-init-file
11152 You can set the initialization file used by the background process
11153 by setting ~org-export-async-init-file~.
11155 - {{{kbd(C-b)}}} ::
11156 #+kindex: C-c C-e C-b
11158 Toggle body-only export. Useful for excluding headers and footers
11159 in the export. Affects only those back-end formats that have
11160 sections like =<head>...</head>= in HTML.
11162 - {{{kbd(C-s)}}} ::
11163 #+kindex: C-c C-e C-s
11165 Toggle sub-tree export. When turned on, Org exports only the
11166 sub-tree starting from point position at the time the export
11167 dispatcher was invoked. Org uses the top heading of this sub-tree
11168 as the document's title. If point is not on a heading, Org uses the
11169 nearest enclosing header. If point is in the document preamble, Org
11170 signals an error and aborts export.
11172 #+vindex: org-export-initial-scope
11173 To make sub-tree export the default, customize the variable
11174 ~org-export-initial-scope~.
11176 - {{{kbd(C-v)}}} ::
11177 #+kindex: C-c C-e C-v
11179 Toggle visible-only export. This is useful for exporting only
11180 certain parts of an Org document by adjusting the visibility of
11181 particular headings.
11185 :DESCRIPTION: Common export settings.
11187 #+cindex: options, for export
11188 #+cindex: Export, settings
11190 #+cindex: @samp{OPTIONS}, keyword
11191 Export options can be set: globally with variables; for an individual
11192 file by making variables buffer-local with in-buffer settings (see
11193 [[*Summary of In-Buffer Settings]]); by setting individual keywords or
11194 specifying them in compact form with the =OPTIONS= keyword; or for
11195 a tree by setting properties (see [[*Properties and Columns]]). Options
11196 set at a specific level override options set at a more general level.
11198 #+cindex: @samp{SETUPFILE}, keyword
11199 In-buffer settings may appear anywhere in the file, either directly or
11200 indirectly through a file included using =#+SETUPFILE: filename or
11201 URL= syntax. Option keyword sets tailored to a particular back-end
11202 can be inserted from the export dispatcher (see [[*The Export
11203 Dispatcher]]) using the =Insert template= command by pressing
11204 {{{kbd(#)}}}. To insert keywords individually, a good way to make
11205 sure the keyword is correct is to type =#+= and then to use
11206 {{{kbd(M-TAB)}}}[fn:16] for completion.
11208 The export keywords available for every back-end, and their equivalent
11209 global variables, include:
11213 #+cindex: @samp{AUTHOR}, keyword
11214 #+vindex: user-full-name
11215 The document author (~user-full-name~).
11219 #+cindex: @samp{CREATOR}, keyword
11220 #+vindex: org-expot-creator-string
11221 Entity responsible for output generation
11222 (~org-export-creator-string~).
11226 #+cindex: @samp{DATE}, keyword
11227 #+vindex: org-export-date-timestamp-format
11228 A date or a time-stamp[fn:121].
11232 #+cindex: @samp{EMAIL}, keyword
11233 #+vindex: user-mail-address
11234 The email address (~user-mail-address~).
11238 #+cindex: @samp{LANGUAGE}, keyword
11239 #+vindex: org-export-default-language
11240 Language to use for translating certain strings
11241 (~org-export-default-language~). With =#+LANGUAGE: fr=, for
11242 example, Org translates =Table of contents= to the French =Table des
11243 matières=[fn:122].
11247 #+cindex: @samp{SELECT_TAGS}, keyword
11248 #+vindex: org-export-select-tags
11249 The default value is =("export")=. When a tree is tagged with
11250 =export= (~org-export-select-tags~), Org selects that tree and its
11251 sub-trees for export. Org excludes trees with =noexport= tags, see
11252 below. When selectively exporting files with =export= tags set, Org
11253 does not export any text that appears before the first headline.
11255 - =EXCLUDE_TAGS= ::
11257 #+cindex: @samp{EXCLUDE_TAGS}, keyword
11258 #+vindex: org-export-exclude-tags
11259 The default value is =("noexport")=. When a tree is tagged with
11260 =noexport= (~org-export-exclude-tags~), Org excludes that tree and
11261 its sub-trees from export. Entries tagged with =noexport= are
11262 unconditionally excluded from the export, even if they have an
11263 =export= tag. Even if a sub-tree is not exported, Org executes any
11264 code blocks contained there.
11268 #+cindex: @samp{TITLE}, keyword
11269 #+cindex: document title
11270 Org displays this title. For long titles, use multiple =#+TITLE=
11273 - =EXPORT_FILE_NAME= ::
11275 #+cindex: @samp{EXPORT_FILE_NAME}, keyword
11276 The name of the output file to be generated. Otherwise, Org
11277 generates the file name based on the buffer name and the extension
11278 based on the back-end format.
11280 The =OPTIONS= keyword is a compact form. To configure multiple
11281 options, use several =OPTIONS= lines. =OPTIONS= recognizes the
11282 following arguments.
11286 #+vindex: org-export-with-smart-quotes
11287 Toggle smart quotes (~org-export-with-smart-quotes~). Depending on
11288 the language used, when activated, Org treats pairs of double quotes
11289 as primary quotes, pairs of single quotes as secondary quotes, and
11290 single quote marks as apostrophes.
11294 #+vindex: org-export-with-emphasize
11295 Toggle emphasized text (~org-export-with-emphasize~).
11299 #+vindex: org-export-with-special-strings
11300 Toggle conversion of special strings
11301 (~org-export-with-special-strings~).
11305 #+vindex: org-export-with-fixed-width
11306 Toggle fixed-width sections (~org-export-with-fixed-width~).
11310 #+vindex: org-export-with-timestamps
11311 Toggle inclusion of time/date active/inactive stamps
11312 (~org-export-with-timestamps~).
11316 #+vindex: org-export-preserve-breaks
11317 Toggles whether to preserve line breaks
11318 (~org-export-preserve-breaks~).
11322 #+vindex: org-export-with-sub-superscripts
11323 Toggle TeX-like syntax for sub- and superscripts. If you write
11324 =^:{}=, =a_{b}= is interpreted, but the simple =a_b= is left as it
11325 is (~org-export-with-sub-superscripts~).
11329 #+vindex: org-export-with-archived-trees
11330 Configure how archived trees are exported. When set to ~headline~,
11331 the export process skips the contents and processes only the
11332 headlines (~org-export-with-archived-trees~).
11336 #+vindex: org-export-with-author
11337 Toggle inclusion of author name into exported file
11338 (~org-export-with-author~).
11340 - ~broken-links~ ::
11342 #+vindex: org-export-with-broken-links
11343 Toggles if Org should continue exporting upon finding a broken
11344 internal link. When set to ~mark~, Org clearly marks the problem
11345 link in the output (~org-export-with-broken-links~).
11349 #+vindex: org-export-with-clocks
11350 Toggle inclusion of CLOCK keywords (~org-export-with-clocks~).
11354 #+vindex: org-export-with-creator
11355 Toggle inclusion of creator information in the exported file
11356 (~org-export-with-creator~).
11360 #+vindex: org-export-with-drawers
11361 Toggles inclusion of drawers, or list of drawers to include, or list
11362 of drawers to exclude (~org-export-with-drawers~).
11366 #+vindex: org-export-with-date
11367 Toggle inclusion of a date into exported file
11368 (~org-export-with-date~).
11372 #+vindex: org-export-with-entities
11373 Toggle inclusion of entities (~org-export-with-entities~).
11377 #+vindex: org-export-with-email
11378 Toggle inclusion of the author's e-mail into exported file
11379 (~org-export-with-email~).
11383 #+vindex: org-export-with-footnotes
11384 Toggle the inclusion of footnotes (~org-export-with-footnotes~).
11388 #+vindex: org-export-headline-levels
11389 Set the number of headline levels for export
11390 (~org-export-headline-levels~). Below that level, headlines are
11391 treated differently. In most back-ends, they become list items.
11395 #+vindex: org-export-with-inlinetasks
11396 Toggle inclusion of inlinetasks (~org-export-with-inlinetasks~).
11400 #+vindex: org-export-with-section-numbers
11401 #+cindex: @samp{UNNUMBERED}, property
11402 Toggle section-numbers (~org-export-with-section-numbers~). When
11403 set to number N, Org numbers only those headlines at level N or
11404 above. Set =UNNUMBERED= property to non-~nil~ to disable numbering
11405 of heading and subheadings entirely. Moreover, when the value is
11406 =notoc= the headline, and all its children, do not appear in the
11407 table of contents either (see [[*Table of Contents]]).
11411 #+vindex: org-export-with-planning
11412 Toggle export of planning information (~org-export-with-planning~).
11413 "Planning information" comes from lines located right after the
11414 headline and contain any combination of these cookies: =SCHEDULED=,
11415 =DEADLINE=, or =CLOSED=.
11419 #+vindex: org-export-with-priority
11420 Toggle inclusion of priority cookies
11421 (~org-export-with-priority~).
11425 #+vindex: org-export-with-properties
11426 Toggle inclusion of property drawers, or list the properties to
11427 include (~org-export-with-properties~).
11431 #+vindex: org-export-with-statistics-cookies
11432 Toggle inclusion of statistics cookies
11433 (~org-export-with-statistics-cookies~).
11437 #+vindex: org-export-with-tags
11438 Toggle inclusion of tags, may also be ~not-in-toc~
11439 (~org-export-with-tags~).
11443 #+vindex: org-export-with-tasks
11444 Toggle inclusion of tasks (TODO items); or ~nil~ to remove all
11445 tasks; or ~todo~ to remove DONE tasks; or list the keywords to keep
11446 (~org-export-with-tasks~).
11450 #+vindex: org-export-with-latex
11451 ~nil~ does not export; ~t~ exports; ~verbatim~ keeps everything in
11452 verbatim (~org-export-with-latex~).
11456 #+vindex: org-export-time-stamp-file
11457 Toggle inclusion of the creation time in the exported file
11458 (~org-export-time-stamp-file~).
11462 #+vindex: org-export-with-title
11463 Toggle inclusion of title (~org-export-with-title~).
11467 #+vindex: org-export-with-toc
11468 Toggle inclusion of the table of contents, or set the level limit
11469 (~org-export-with-toc~).
11473 #+vindex: org-export-with-todo-keywords
11474 Toggle inclusion of TODO keywords into exported text
11475 (~org-export-with-todo-keywords~).
11479 #+vindex: org-export-with-tables
11480 Toggle inclusion of tables (~org-export-with-tables~).
11482 When exporting sub-trees, special node properties can override the
11483 above keywords. These properties have an =EXPORT_= prefix. For
11484 example, =DATE= becomes, =EXPORT_DATE= when used for a specific
11485 sub-tree. Except for =SETUPFILE=, all other keywords listed above
11486 have an =EXPORT_= equivalent.
11488 #+cindex: @samp{BIND}, keyword
11489 #+vindex: org-export-allow-bind-keywords
11490 If ~org-export-allow-bind-keywords~ is non-~nil~, Emacs variables can
11491 become buffer-local during export by using the =BIND= keyword. Its
11492 syntax is =#+BIND: variable value=. This is particularly useful for
11493 in-buffer settings that cannot be changed using keywords.
11495 ** Table of Contents
11497 :DESCRIPTION: The if and where of the table of contents.
11499 #+cindex: table of contents
11500 #+cindex: list of tables
11501 #+cindex: list of listings
11503 #+cindex: @samp{toc}, in @samp{OPTIONS} keyword
11504 #+vindex: org-export-with-toc
11505 The table of contents includes all headlines in the document. Its
11506 depth is therefore the same as the headline levels in the file. If
11507 you need to use a different depth, or turn it off entirely, set the
11508 ~org-export-with-toc~ variable accordingly. You can achieve the same
11509 on a per file basis, using the following =toc= item in =OPTIONS=
11513 ,#+OPTIONS: toc:2 (only include two levels in TOC)
11514 ,#+OPTIONS: toc:nil (no default TOC at all)
11517 #+cindex: excluding entries from table of contents
11518 #+cindex: table of contents, exclude entries
11519 Org includes both numbered and unnumbered headlines in the table of
11520 contents[fn:123]. If you need to exclude an unnumbered headline,
11521 along with all its children, set the =UNNUMBERED= property to =notoc=
11525 ,* Subtree not numbered, not in table of contents either
11531 #+cindex: @samp{TOC}, keyword
11532 Org normally inserts the table of contents directly before the first
11533 headline of the file. To move the table of contents to a different
11534 location, first turn off the default with ~org-export-with-toc~
11535 variable or with =#+OPTIONS: toc:nil=. Then insert =#+TOC: headlines
11536 N= at the desired location(s).
11539 ,#+OPTIONS: toc:nil
11541 ,#+TOC: headlines 2
11544 To adjust the table of contents depth for a specific section of the
11545 Org document, append an additional =local= parameter. This parameter
11546 becomes a relative depth for the current level. The following example
11547 inserts a local table of contents, with direct children only.
11551 ,#+TOC: headlines 1 local
11554 Note that for this feature to work properly in LaTeX export, the Org
11555 file requires the inclusion of the titletoc package. Because of
11556 compatibility issues, titletoc has to be loaded /before/ hyperref.
11557 Customize the ~org-latex-default-packages-alist~ variable.
11559 Use the =TOC= keyword to generate list of tables---respectively, all
11560 listings---with captions.
11567 #+cindex: @samp{ALT_TITLE}, property
11568 Normally Org uses the headline for its entry in the table of contents.
11569 But with =ALT_TITLE= property, a different entry can be specified for
11570 the table of contents.
11574 :DESCRIPTION: Include additional files into a document.
11576 #+cindex: include files, during export
11577 #+cindex: export, include files
11578 #+cindex: @samp{INCLUDE}, keyword
11580 During export, you can include the content of another file. For
11581 example, to include your =.emacs= file, you could use:
11583 : #+INCLUDE: "~/.emacs" src emacs-lisp
11585 #+texinfo: @noindent
11586 The first parameter is the file name to include. The optional second
11587 parameter specifies the block type: =example=, =export= or =src=. The
11588 optional third parameter specifies the source code language to use for
11589 formatting the contents. This is relevant to both =export= and =src=
11592 If an included file is specified as having a markup language, Org
11593 neither checks for valid syntax nor changes the contents in any way.
11594 For example and source blocks, Org code-escapes the contents before
11597 #+cindex: @samp{minlevel}, include
11598 If an included file is not specified as having any markup language,
11599 Org assumes it be in Org format and proceeds as usual with a few
11600 exceptions. Org makes the footnote labels (see [[*Creating Footnotes]])
11601 in the included file local to that file. The contents of the included
11602 file belong to the same structure---headline, item---containing the
11603 =INCLUDE= keyword. In particular, headlines within the file become
11604 children of the current section. That behavior can be changed by
11605 providing an additional keyword parameter, =:minlevel=. It shifts the
11606 headlines in the included file to become the lowest level. For
11607 example, this syntax makes the included file a sibling of the current
11608 top-level headline:
11610 : #+INCLUDE: "~/my-book/chapter2.org" :minlevel 1
11612 #+cindex: @samp{lines}, include
11613 Inclusion of only portions of files are specified using ranges
11614 parameter with =:lines= keyword. The line at the upper end of the
11615 range will not be included. The start and/or the end of the range may
11616 be omitted to use the obvious defaults.
11618 | =#+INCLUDE: "~/.emacs" :lines "5-10"= | Include lines 5 to 10, 10 excluded |
11619 | =#+INCLUDE: "~/.emacs" :lines "-10"= | Include lines 1 to 10, 10 excluded |
11620 | =#+INCLUDE: "~/.emacs" :lines "10-"= | Include lines from 10 to EOF |
11622 Inclusions may specify a file-link to extract an object matched by
11623 ~org-link-search~[fn:124] (see [[*Search Options in File Links]]). The
11624 ranges for =:lines= keyword are relative to the requested element.
11627 : #+INCLUDE: "./paper.org::*conclusion" :lines 1-20
11629 #+texinfo: @noindent
11630 includes the first 20 lines of the headline named =conclusion=.
11632 #+cindex: @samp{only-contents}, include
11633 To extract only the contents of the matched object, set
11634 =:only-contents= property to non-~nil~. This omits any planning lines
11635 or property drawers. For example, to include the body of the heading
11636 with the custom ID =theory=, you can use
11638 : #+INCLUDE: "./paper.org::#theory" :only-contents t
11640 The following command allows navigating back and forth to the included
11643 - {{{kbd(C-c ')}}} (~org-edit~special~) ::
11645 #+findex: org-edit-special
11647 Visit the included file at point.
11649 ** Macro Replacement
11651 :DESCRIPTION: Use macros to create templates.
11653 #+cindex: macro replacement, during export
11654 #+cindex: @samp{MACRO}, keyword
11656 #+vindex: org-export-global-macros
11657 Macros replace text snippets during export. Macros are defined
11658 globally in ~org-export-global-macros~, or document-wise with the
11661 : #+MACRO: name replacement text; $1, $2 are arguments
11663 #+texinfo: @noindent
11664 which can be referenced using ={{{name(arg1, arg2)}}}=[fn:125]. For
11668 ,#+MACRO: poem Rose is $1, violet's $2. Life's ordered: Org assists you.
11669 {{{poem(red,blue)}}}
11672 #+texinfo: @noindent
11675 : Rose is red, violet's blue. Life's ordered: Org assists you.
11677 As a special case, Org parses any replacement text starting with
11678 =(eval= as an Emacs Lisp expression and evaluates it accordingly.
11679 Within such templates, arguments become strings. Thus, the following
11682 : #+MACRO: gnustamp (eval (concat "GNU/" (capitalize $1)))
11684 #+texinfo: @noindent
11685 turns ={{{gnustamp(linux)}}}= into =GNU/Linux= during export.
11687 Org recognizes macro references in following Org markup areas:
11688 paragraphs, headlines, verse blocks, tables cells and lists. Org also
11689 recognizes macro references in keywords, such as =CAPTION=, =TITLE=,
11690 =AUTHOR=, =DATE=, and for some back-end specific export options.
11692 Org comes with following pre-defined macros:
11694 #+attr_texinfo: :sep ;
11695 - ={{{keyword(NAME)}}}=; ={{{title}}}=; ={{{author}}}=; ={{{email}}}= ::
11697 #+cindex: @samp{keyword}, macro
11698 #+cindex: @samp{title}, macro
11699 #+cindex: @samp{author}, macro
11700 #+cindex: @samp{email}, macro
11701 The =keyword= macro collects all values from {{{var(NAME)}}}
11702 keywords throughout the buffer, separated with white space.
11703 =title=, =author= and =email= macros are shortcuts for,
11704 respectively, ={{{keyword(TITLE)}}}=, ={{{keyword(AUTHOR)}}}= and
11705 ={{{keyword(EMAIL)}}}=.
11707 - ={{{date}}}=; ={{{date(FORMAT)}}}= ::
11709 #+cindex: @samp{date}, macro
11710 This macro refers to the =DATE= keyword. {{{var(FORMAT)}}} is an
11711 optional argument to the =date= macro that is used only if =DATE= is
11712 a single timestamp. {{{var(FORMAT)}}} should be a format string
11713 understood by ~format-time-string~.
11715 - ={{{time(FORMAT)}}}=; ={{{modification-time(FORMAT, VC)}}}= ::
11717 #+cindex: @samp{time}, macro
11718 #+cindex: @samp{modification-time}, macro
11719 These macros refer to the document's date and time of export and
11720 date and time of modification. {{{var(FORMAT)}}} is a string
11721 understood by ~format-time-string~. If the second argument to the
11722 ~modification-time~ macro is non-~nil~, Org uses =vc.el= to retrieve
11723 the document's modification time from the version control system.
11724 Otherwise Org reads the file attributes.
11726 - ={{{input-file}}}= ::
11728 #+cindex: @samp{input-file}, macro
11729 This macro refers to the filename of the exported file.
11731 - ={{{property(PROPERTY-NAME)}}}=; ={{{property(PROPERTY-NAME, SEARCH OPTION)}}}= ::
11733 #+cindex: @samp{property}, macro
11734 This macro returns the value of property {{{var(PROPERTY-NAME)}}} in
11735 the current entry. If {{{var(SEARCH-OPTION)}}} (see [[*Search
11736 Options in File Links]]) refers to a remote entry, use it instead.
11738 - ={{{n}}}=; ={{{n(NAME)}}}=; ={{{n(NAME, ACTION)}}}= ::
11740 #+cindex: @samp{n}, macro
11741 #+cindex: counter, macro
11742 This macro implements custom counters by returning the number of
11743 times the macro has been expanded so far while exporting the buffer.
11744 You can create more than one counter using different {{{var(NAME)}}}
11745 values. If {{{var(ACTION)}}} is =-=, previous value of the counter
11746 is held, i.e., the specified counter is not incremented. If the
11747 value is a number, the specified counter is set to that value. If
11748 it is any other non-empty string, the specified counter is reset
11749 to 1. You may leave {{{var(NAME)}}} empty to reset the default
11752 #+cindex: @samp{results}, macro
11753 Moreover, inline source blocks (see [[*Structure of Code Blocks]]) use the
11754 special =results= macro to mark their output. As such, you are
11755 advised against re-defining it, unless you know what you are doing.
11757 #+vindex: org-hide-macro-markers
11758 The surrounding brackets can be made invisible by setting
11759 ~org-hide-macro-markers~ to a non-~nil~ value.
11761 Org expands macros at the very beginning of the export process.
11765 :DESCRIPTION: What will not be exported.
11767 #+cindex: exporting, not
11769 #+cindex: comment lines
11770 Lines starting with zero or more whitespace characters followed by one
11771 =#= and a whitespace are treated as comments and, as such, are not
11774 #+cindex: @samp{BEGIN_COMMENT}
11775 #+cindex: comment block
11776 Likewise, regions surrounded by =#+BEGIN_COMMENT= ... =#+END_COMMENT=
11779 #+cindex: comment trees
11780 Finally, a =COMMENT= keyword at the beginning of an entry, but after
11781 any other keyword or priority cookie, comments out the entire subtree.
11782 In this case, the subtree is not exported and no code block within it
11783 is executed either[fn:126]. The command below helps changing the
11784 comment status of a headline.
11786 - {{{kbd(C-c ;)}}} (~org-toggle-comment~) ::
11788 #+findex: org-toggle-comment
11790 Toggle the =COMMENT= keyword at the beginning of an entry.
11792 ** ASCII/Latin-1/UTF-8 export
11794 :DESCRIPTION: Exporting to flat files with encoding.
11796 #+cindex: ASCII export
11797 #+cindex: Latin-1 export
11798 #+cindex: UTF-8 export
11800 ASCII export produces an output file containing only plain ASCII
11801 characters. This is the simplest and most direct text output. It
11802 does not contain any Org markup. Latin-1 and UTF-8 export use
11803 additional characters and symbols available in these encoding
11804 standards. All three of these export formats offer the most basic of
11805 text output for maximum portability.
11807 #+vindex: org-ascii-text-width
11808 On export, Org fills and justifies text according to the text width
11809 set in ~org-ascii-text-width~.
11811 #+vindex: org-ascii-links-to-notes
11812 Org exports links using a footnote-like style where the descriptive
11813 part is in the text and the link is in a note before the next heading.
11814 See the variable ~org-ascii-links-to-notes~ for details.
11816 *** ASCII export commands
11821 #+attr_texinfo: :sep ,
11822 - {{{kbd(C-c C-e t a)}}} (~org-ascii-export-to-ascii~), {{{kbd(C-c C-e t l)}}}, {{{kbd(C-c C-e t u)}}} ::
11823 #+kindex: C-c C-e t a
11824 #+kindex: C-c C-e t l
11825 #+kindex: C-c C-e t u
11826 #+findex: org-ascii-export-to-ascii
11828 Export as an ASCII file with a =.txt= extension. For =myfile.org=,
11829 Org exports to =myfile.txt=, overwriting without warning. For
11830 =myfile.txt=, Org exports to =myfile.txt.txt= in order to prevent
11833 #+attr_texinfo: :sep ,
11834 - {{{kbd(C-c C-e t A)}}} (~org-ascii-export-to-ascii~), {{{kbd(C-c C-e t L)}}}, {{{kbd(C-c C-e t U)}}} ::
11835 #+kindex: C-c C-e t A
11836 #+kindex: C-c C-e t L
11837 #+kindex: C-c C-e t U
11838 #+findex: org-ascii-export-to-ascii
11840 Export to a temporary buffer. Does not create a file.
11842 *** ASCII specific export settings
11847 The ASCII export back-end has one extra keyword for customizing ASCII
11848 output. Setting this keyword works similar to the general options
11849 (see [[*Export Settings]]).
11853 #+cindex: @samp{SUBTITLE}, keyword
11854 The document subtitle. For long subtitles, use multiple
11855 =#+SUBTITLE= lines in the Org file. Org prints them on one
11856 continuous line, wrapping into multiple lines if necessary.
11858 *** Header and sectioning structure
11863 Org converts the first three outline levels into headlines for ASCII
11864 export. The remaining levels are turned into lists. To change this
11865 cut-off point where levels become lists, see [[*Export Settings]].
11867 *** Quoting ASCII text
11872 To insert text within the Org file by the ASCII back-end, use one the
11873 following constructs, inline, keyword, or export block:
11875 #+cindex: @samp{ASCII}, keyword
11876 #+cindex: @samp{BEGIN_EXPORT ascii}
11878 Inline text @@ascii:and additional text@@ within a paragraph.
11880 ,#+ASCII: Some text
11882 ,#+BEGIN_EXPORT ascii
11883 Org exports text in this block only when using ASCII back-end.
11887 *** ASCII specific attributes
11891 #+cindex: @samp{ATTR_ASCII}, keyword
11892 #+cindex: horizontal rules, in ASCII export
11894 ASCII back-end recognizes only one attribute, =:width=, which
11895 specifies the width of a horizontal rule in number of characters. The
11896 keyword and syntax for specifying widths is:
11899 ,#+ATTR_ASCII: :width 10
11903 *** ASCII special blocks
11907 #+cindex: special blocks, in ASCII export
11908 #+cindex: @samp{BEGIN_JUSTIFYLEFT}
11909 #+cindex: @samp{BEGIN_JUSTIFYRIGHT}
11911 Besides =#+BEGIN_CENTER= blocks (see [[*Paragraphs]]), ASCII back-end has
11912 these two left and right justification blocks:
11915 ,#+BEGIN_JUSTIFYLEFT
11916 It's just a jump to the left...
11919 ,#+BEGIN_JUSTIFYRIGHT
11920 ...and then a step to the right.
11921 ,#+END_JUSTIFYRIGHT
11925 #+cindex: Beamer export
11927 Org uses Beamer export to convert an Org file tree structure into
11928 high-quality interactive slides for presentations. Beamer is a LaTeX
11929 document class for creating presentations in PDF, HTML, and other
11930 popular display formats.
11932 *** Beamer export commands
11934 :DESCRIPTION: For creating Beamer documents.
11937 - {{{kbd(C-c C-e l b)}}} (~org-beamer-export-to-latex~) ::
11938 #+kindex: C-c C-e l b
11939 #+findex: org-beamer-export-to-latex
11941 Export as LaTeX file with a =.tex= extension. For =myfile.org=, Org
11942 exports to =myfile.tex=, overwriting without warning.
11944 - {{{kbd(C-c C-e l B)}}} (~org-beamer-export-as-latex~) ::
11945 #+kindex: C-c C-e l B
11946 #+findex: org-beamer-export-as-latex
11948 Export to a temporary buffer. Does not create a file.
11950 - {{{kbd(C-c C-e l P)}}} (~org-beamer-export-to-pdf~) ::
11951 #+kindex: C-c C-e l P
11952 #+findex: org-beamer-export-to-pdf
11954 Export as LaTeX file and then convert it to PDF format.
11956 - {{{kbd(C-c C-e l O)}}} ::
11957 #+kindex: C-c C-e l O
11959 Export as LaTeX file, convert it to PDF format, and then open the
11962 *** Beamer specific export settings
11964 :DESCRIPTION: For customizing Beamer export.
11967 Beamer export back-end has several additional keywords for customizing
11968 Beamer output. These keywords work similar to the general options
11969 settings (see [[*Export Settings]]).
11971 - =BEAMER_THEME= ::
11973 #+cindex: @samp{BEAMER_THEME}, keyword
11974 #+vindex: org-beamer-theme
11975 The Beamer layout theme (~org-beamer-theme~). Use square brackets
11976 for options. For example:
11978 : #+BEAMER_THEME: Rochester [height=20pt]
11980 - =BEAMER_FONT_THEME= ::
11982 #+cindex: @samp{BEAMER_FONT_THEME}, keyword
11983 The Beamer font theme.
11985 - =BEAMER_INNER_THEME= ::
11987 #+cindex: @samp{BEAMER_INNER_THEME}, keyword
11988 The Beamer inner theme.
11990 - =BEAMER_OUTER_THEME= ::
11992 #+cindex: @samp{BEAMER_OUTER_THEME}, keyword
11993 The Beamer outer theme.
11995 - =BEAMER_HEADER= ::
11997 #+cindex: @samp{BEAMER_HEADER}, keyword
11998 Arbitrary lines inserted in the preamble, just before the =hyperref=
12003 #+cindex: @samp{DESCRIPTION}, keyword
12004 The document description. For long descriptions, use multiple
12005 =DESCRIPTION= keywords. By default, =hyperref= inserts
12006 =DESCRIPTION= as metadata. Use ~org-latex-hyperref-template~ to
12007 configure document metadata. Use ~org-latex-title-command~ to
12008 configure typesetting of description as part of front matter.
12012 #+cindex: @samp{KEYWORDS}, keyword
12013 The keywords for defining the contents of the document. Use
12014 multiple =KEYWORDS= lines if necessary. By default, =hyperref=
12015 inserts =KEYWORDS= as metadata. Use ~org-latex-hyperref-template~
12016 to configure document metadata. Use ~org-latex-title-command~ to
12017 configure typesetting of keywords as part of front matter.
12021 #+cindex: @samp{SUBTITLE}, keyword
12022 Document's subtitle. For typesetting, use
12023 ~org-beamer-subtitle-format~ string. Use
12024 ~org-latex-hyperref-template~ to configure document metadata. Use
12025 ~org-latex-title-command~ to configure typesetting of subtitle as
12026 part of front matter.
12028 *** Frames and Blocks in Beamer
12030 :DESCRIPTION: For composing Beamer slides.
12033 Org transforms heading levels into Beamer's sectioning elements,
12034 frames and blocks. Any Org tree with a not-too-deep-level nesting
12035 should in principle be exportable as a Beamer presentation.
12038 #+vindex: org-beamer-frame-level
12039 Org headlines become Beamer frames when the heading level in Org is
12040 equal to ~org-beamer-frame-level~ or =H= value in a =OPTIONS= line
12041 (see [[*Export Settings]]).
12043 #+cindex: @samp{BEAMER_ENV}, property
12044 Org overrides headlines to frames conversion for the current tree of
12045 an Org file if it encounters the =BEAMER_ENV= property set to
12046 =frame= or =fullframe=. Org ignores whatever
12047 ~org-beamer-frame-level~ happens to be for that headline level in
12048 the Org tree. In Beamer terminology, a full frame is a frame
12051 - Org exports a Beamer frame's objects as block environments. Org can
12052 enforce wrapping in special block types when =BEAMER_ENV= property
12053 is set[fn:127]. For valid values see
12054 ~org-beamer-environments-default~. To add more values, see
12055 ~org-beamer-environments-extra~.
12056 #+vindex: org-beamer-environments-default
12057 #+vindex: org-beamer-environments-extra
12060 #+cindex: @samp{BEAMER_REF}, property
12061 If =BEAMER_ENV= is set to =appendix=, Org exports the entry as an
12062 appendix. When set to =note=, Org exports the entry as a note
12063 within the frame or between frames, depending on the entry's heading
12064 level. When set to =noteNH=, Org exports the entry as a note
12065 without its title. When set to =againframe=, Org exports the entry
12066 with =\againframe= command, which makes setting the =BEAMER_REF=
12067 property mandatory because =\againframe= needs frame to resume.
12069 When =ignoreheading= is set, Org export ignores the entry's headline
12070 but not its content. This is useful for inserting content between
12071 frames. It is also useful for properly closing a =column=
12072 environment. @end itemize
12074 #+cindex: @samp{BEAMER_ACT}, property
12075 #+cindex: @samp{BEAMER_OPT}, property
12076 When =BEAMER_ACT= is set for a headline, Org export translates that
12077 headline as an overlay or action specification. When enclosed in
12078 square brackets, Org export makes the overlay specification
12079 a default. Use =BEAMER_OPT= to set any options applicable to the
12080 current Beamer frame or block. The Beamer export back-end wraps
12081 with appropriate angular or square brackets. It also adds the
12082 =fragile= option for any code that may require a verbatim block.
12084 #+cindex: @samp{BEAMER_COL}, property
12085 To create a column on the Beamer slide, use the =BEAMER_COL=
12086 property for its headline in the Org file. Set the value of
12087 =BEAMER_COL= to a decimal number representing the fraction of the
12088 total text width. Beamer export uses this value to set the column's
12089 width and fills the column with the contents of the Org entry. If
12090 the Org entry has no specific environment defined, Beamer export
12091 ignores the heading. If the Org entry has a defined environment,
12092 Beamer export uses the heading as title. Behind the scenes, Beamer
12093 export automatically handles LaTeX column separations for contiguous
12094 headlines. To manually adjust them for any unique configurations
12095 needs, use the =BEAMER_ENV= property.
12097 *** Beamer specific syntax
12099 :DESCRIPTION: For using in Org documents.
12102 Since Org's Beamer export back-end is an extension of the LaTeX
12103 back-end, it recognizes other LaTeX specific syntax---for example,
12104 =#+LATEX:= or =#+ATTR_LATEX:=. See [[*LaTeX Export]], for details.
12106 Beamer export wraps the table of contents generated with =toc:t=
12107 =OPTION= keyword in a =frame= environment. Beamer export does not
12108 wrap the table of contents generated with =TOC= keyword (see [[*Table of
12109 Contents]]). Use square brackets for specifying options.
12111 : #+TOC: headlines [currentsection]
12113 Insert Beamer-specific code using the following constructs:
12115 #+cindex: @samp{BEAMER}, keyword
12116 #+cindex: @samp{BEGIN_EXPORT beamer}
12120 ,#+BEGIN_EXPORT beamer
12121 Only Beamer export back-end exports this.
12124 Text @@beamer:some code@@ within a paragraph.
12127 Inline constructs, such as the last one above, are useful for adding
12128 overlay specifications to objects with ~bold~, ~item~, ~link~,
12129 ~radio-target~ and ~target~ types. Enclose the value in angular
12130 brackets and place the specification at the beginning of the object as
12131 shown in this example:
12133 : A *@@beamer:<2->@@useful* feature
12135 #+cindex: @samp{ATTR_BEAMER}, keyword
12136 Beamer export recognizes the =ATTR_BEAMER= keyword with the following
12137 attributes from Beamer configurations: =:environment= for changing
12138 local Beamer environment, =:overlay= for specifying Beamer overlays in
12139 angular or square brackets, and =:options= for inserting optional
12143 ,#+ATTR_BEAMER: :environment nonindentlist
12144 - item 1, not indented
12145 - item 2, not indented
12146 - item 3, not indented
12150 ,#+ATTR_BEAMER: :overlay <+->
12156 ,#+ATTR_BEAMER: :options [Lagrange]
12157 Let $G$ be a finite group, and let $H$ be
12158 a subgroup of $G$. Then the order of $H$ divides the order of $G$.
12161 *** Editing support
12163 :DESCRIPTION: Editing support.
12166 The ~org-beamer-mode~ is a special minor mode for faster editing of
12169 : #+STARTUP: beamer
12171 - {{{kbd(C-c C-b)}}} (~org-beamer-select-environment~) ::
12173 #+findex: org-beamer-select-environment
12175 The ~org-beamer-mode~ provides this key for quicker selections in
12176 Beamer normal environments, and for selecting the =BEAMER_COL=
12179 *** A Beamer example
12181 :DESCRIPTION: A complete presentation.
12184 Here is an example of an Org document ready for Beamer export.
12187 ,#+TITLE: Example Presentation
12188 ,#+AUTHOR: Carsten Dominik
12189 ,#+OPTIONS: H:2 toc:t num:t
12190 ,#+LATEX_CLASS: beamer
12191 ,#+LATEX_CLASS_OPTIONS: [presentation]
12192 ,#+BEAMER_THEME: Madrid
12193 ,#+COLUMNS: %45ITEM %10BEAMER_ENV(Env) %10BEAMER_ACT(Act) %4BEAMER_COL(Col)
12195 ,* This is the first structural section
12198 ,*** Thanks to Eric Fraga :B_block:
12203 for the first viable Beamer setup in Org
12204 ,*** Thanks to everyone else :B_block:
12210 for contributing to the discussion
12211 ,**** This will be formatted as a beamer note :B_note:
12215 ,** Frame 2 (where we will not use columns)
12217 Please test this stuff!
12222 :DESCRIPTION: Exporting to HTML.
12224 #+cindex: HTML export
12226 Org mode contains an HTML exporter with extensive HTML formatting
12227 compatible with XHTML 1.0 strict standard.
12229 *** HTML export commands
12231 :DESCRIPTION: Invoking HTML export.
12234 - {{{kbd(C-c C-e h h)}}} (~org-html-export-to-html~) ::
12235 #+kindex: C-c C-e h h
12236 #+kindex: C-c C-e h o
12237 #+findex: org-html-export-to-html
12239 Export as HTML file with a =.html= extension. For =myfile.org=, Org
12240 exports to =myfile.html=, overwriting without warning. {{{kbd{C-c
12241 C-e h o)}}} exports to HTML and opens it in a web browser.
12243 - {{{kbd(C-c C-e h H)}}} (~org-html-export-as-html~) ::
12244 #+kindex: C-c C-e h H
12245 #+findex: org-html-export-as-html
12247 Exports to a temporary buffer. Does not create a file.
12249 *** HTML specific export settings
12251 :DESCRIPTION: Settings for HTML export.
12254 HTML export has a number of keywords, similar to the general options
12255 settings described in [[*Export Settings]].
12259 #+cindex: @samp{DESCRIPTION}, keyword
12260 This is the document's description, which the HTML exporter inserts
12261 it as a HTML meta tag in the HTML file. For long descriptions, use
12262 multiple =DESCRIPTION= lines. The exporter takes care of wrapping
12263 the lines properly.
12265 - =HTML_DOCTYPE= ::
12267 #+cindex: @samp{HTML_DOCTYPE}, keyword
12268 #+vindex: org-html-doctype
12269 Specify the document type, for example: HTML5 (~org-html-doctype~).
12271 - =HTML_CONTAINER= ::
12273 #+cindex: @samp{HTML_CONTAINER}, keyword
12274 #+vindex: org-html-container-element
12275 Specify the HTML container, such as =div=, for wrapping sections and
12276 elements (~org-html-container-element~).
12278 - =HTML_LINK_HOME= ::
12280 #+cindex: @samp{HTML_LINK_HOME}, keyword
12281 #+vindex: org-html-link-home
12282 The URL for home link (~org-html-link-home~).
12284 - =HTML_LINK_UP= ::
12286 #+cindex: @samp{HTML_LINK_UP}, keyword
12287 #+vindex: org-html-link-up
12288 The URL for the up link of exported HTML pages (~org-html-link-up~).
12290 - =HTML_MATHJAX= ::
12292 #+cindex: @samp{HTML_MATHJAX}, keyword
12293 #+vindex: org-html-mathjax-options
12294 Options for MathJax (~org-html-mathjax-options~). MathJax is used
12295 to typeset LaTeX math in HTML documents. See [[*Math formatting in
12296 HTML export]], for an example.
12300 #+cindex: @samp{HTML_HEAD}, keyword
12301 #+vindex: org-html-head
12302 Arbitrary lines for appending to the HTML document's head
12305 - =HTML_HEAD_EXTRA= ::
12307 #+cindex: @samp{HTML_HEAD_EXTRA}, keyword
12308 #+vindex: org-html-head-extra
12309 More arbitrary lines for appending to the HTML document's head
12310 (~org-html-head-extra~).
12314 #+cindex: @samp{KEYWORDS}, keyword
12315 Keywords to describe the document's content. HTML exporter inserts
12316 these keywords as HTML meta tags. For long keywords, use multiple
12319 - =LATEX_HEADER= ::
12321 #+cindex: @samp{LATEX_HEADER}, keyword
12322 Arbitrary lines for appending to the preamble; HTML exporter appends
12323 when transcoding LaTeX fragments to images (see [[*Math formatting in
12328 #+cindex: @samp{SUBTITLE}, keyword
12329 The document's subtitle. HTML exporter formats subtitle if document
12330 type is =HTML5= and the CSS has a =subtitle= class.
12332 Some of these keywords are explained in more detail in the following
12333 sections of the manual.
12337 :DESCRIPTION: Exporting various (X)HTML flavors.
12340 Org can export to various (X)HTML flavors.
12342 #+vindex: org-html-doctype
12343 #+vindex: org-html-doctype-alist
12344 Set the ~org-html-doctype~ variable for different (X)HTML variants.
12345 Depending on the variant, the HTML exporter adjusts the syntax of HTML
12346 conversion accordingly. Org includes the following ready-made
12350 - ~"html4-transitional"~
12351 - ~"html4-frameset"~
12353 - ~"xhtml-transitional"~
12354 - ~"xhtml-frameset"~
12359 #+texinfo: @noindent
12360 See the variable ~org-html-doctype-alist~ for details. The default is
12363 #+vindex: org-html-html5-fancy
12364 #+cindex: @samp{HTML5}, export new elements
12365 Org's HTML exporter does not by default enable new block elements
12366 introduced with the HTML5 standard. To enable them, set
12367 ~org-html-html5-fancy~ to non-~nil~. Or use an =OPTIONS= line in the
12368 file to set =html5-fancy=.
12370 HTML5 documents can now have arbitrary =#+BEGIN= ... =#+END= blocks.
12379 #+texinfo: @noindent
12388 #+texinfo: @noindent
12392 ,#+ATTR_HTML: :controls controls :width 350
12394 ,#+HTML: <source src="movie.mp4" type="video/mp4">
12395 ,#+HTML: <source src="movie.ogg" type="video/ogg">
12396 Your browser does not support the video tag.
12400 #+texinfo: @noindent
12404 <video controls="controls" width="350">
12405 <source src="movie.mp4" type="video/mp4">
12406 <source src="movie.ogg" type="video/ogg">
12407 <p>Your browser does not support the video tag.</p>
12411 #+vindex: org-html-html5-elements
12412 When special blocks do not have a corresponding HTML5 element, the
12413 HTML exporter reverts to standard translation (see
12414 ~org-html-html5-elements~). For example, =#+BEGIN_lederhosen= exports
12415 to ~<div class="lederhosen">~.
12417 Special blocks cannot have headlines. For the HTML exporter to wrap
12418 the headline and its contents in ~<section>~ or ~<article>~ tags, set
12419 the =HTML_CONTAINER= property for the headline.
12421 *** HTML preamble and postamble
12423 :DESCRIPTION: Inserting preamble and postamble.
12425 #+vindex: org-html-preamble
12426 #+vindex: org-html-postamble
12427 #+vindex: org-html-preamble-format
12428 #+vindex: org-html-postamble-format
12429 #+vindex: org-html-validation-link
12430 #+vindex: org-export-creator-string
12431 #+vindex: org-export-time-stamp-file
12433 The HTML exporter has delineations for preamble and postamble. The
12434 default value for ~org-html-preamble~ is ~t~, which makes the HTML
12435 exporter insert the preamble. See the variable
12436 ~org-html-preamble-format~ for the format string.
12438 Set ~org-html-preamble~ to a string to override the default format
12439 string. If the string is a function, the HTML exporter expects the
12440 function to return a string upon execution. The HTML exporter inserts
12441 this string in the preamble. The HTML exporter does not insert
12442 a preamble if ~org-html-preamble~ is set ~nil~.
12444 The default value for ~org-html-postamble~ is ~auto~, which makes the
12445 HTML exporter build a postamble from looking up author's name, email
12446 address, creator's name, and date. Set ~org-html-postamble~ to ~t~ to
12447 insert the postamble in the format specified in the
12448 ~org-html-postamble-format~ variable. The HTML exporter does not
12449 insert a postamble if ~org-html-postamble~ is set to ~nil~.
12451 *** Quoting HTML tags
12453 :DESCRIPTION: Using direct HTML in Org files.
12456 The HTML export back-end transforms =<= and =>= to =<= and =>=.
12458 To include raw HTML code in the Org file so the HTML export back-end
12459 can insert that HTML code in the output, use this inline syntax:
12460 =@@html:...@@=. For example:
12462 : @@html:<b>@@bold text@@html:</b>@@
12464 #+cindex: @samp{HTML}, keyword
12465 #+cindex: @samp{BEGIN_EXPORT html}
12466 For larger raw HTML code blocks, use these HTML export code blocks:
12469 ,#+HTML: Literal HTML code for export
12471 ,#+BEGIN_EXPORT html
12472 All lines between these markers are exported literally
12476 *** Headlines in HTML export
12478 :DESCRIPTION: Formatting headlines.
12480 #+cindex: headlines, in HTML export
12482 Headlines are exported to =<h1>=, =<h2>=, etc. Each headline gets the
12483 =id= attribute from =CUSTOM_ID= property, or a unique generated value,
12484 see [[*Internal Links]].
12486 #+vindex: org-html-self-link-headlines
12487 When ~org-html-self-link-headlines~ is set to a non-~nil~ value, the
12488 text of the headlines is also wrapped in =<a>= tags. These tags have
12489 a =href= attribute making the headlines link to themselves.
12491 *** Links in HTML export
12493 :DESCRIPTION: Inserting and formatting links.
12495 #+cindex: links, in HTML export
12496 #+cindex: internal links, in HTML export
12497 #+cindex: external links, in HTML export
12499 The HTML export back-end transforms Org's internal links (see
12500 [[*Internal Links]]) to equivalent HTML links in the output. The back-end
12501 similarly handles Org's automatic links created by radio targets (see
12502 [[*Radio Targets]]) similarly. For Org links to external files, the
12503 back-end transforms the links to /relative/ paths.
12505 #+vindex: org-html-link-org-files-as-html
12506 For Org links to other =.org= files, the back-end automatically
12507 changes the file extension to =.html= and makes file paths relative.
12508 If the =.org= files have an equivalent =.html= version at the same
12509 location, then the converted links should work without any further
12510 manual intervention. However, to disable this automatic path
12511 translation, set ~org-html-link-org-files-as-html~ to ~nil~. When
12512 disabled, the HTML export back-end substitutes the ID-based links in
12513 the HTML output. For more about linking files when publishing to
12514 a directory, see [[*Publishing links]].
12516 Org files can also have special directives to the HTML export
12517 back-end. For example, by using =#+ATTR_HTML= lines to specify new
12518 format attributes to ~<a>~ or ~<img>~ tags. This example shows
12519 changing the link's title and style:
12521 #+cindex: @samp{ATTR_HTML}, keyword
12523 ,#+ATTR_HTML: :title The Org mode homepage :style color:red;
12524 [[https://orgmode.org]]
12527 *** Tables in HTML export
12529 :DESCRIPTION: How to modify the formatting of tables.
12531 #+cindex: tables, in HTML
12532 #+vindex: org-export-html-table-tag
12534 The HTML export back-end uses ~org-html-table-default-attributes~ when
12535 exporting Org tables to HTML. By default, the exporter does not draw
12536 frames and cell borders. To change for this for a table, use the
12537 following lines before the table in the Org file:
12539 #+cindex: @samp{CAPTION}, keyword
12540 #+cindex: @samp{ATTR_HTML}, keyword
12542 ,#+CAPTION: This is a table with lines around and between cells
12543 ,#+ATTR_HTML: border="2" rules="all" frame="border"
12546 The HTML export back-end preserves column groupings in Org tables (see
12547 [[*Column Groups]]) when exporting to HTML.
12549 Additional options for customizing tables for HTML export.
12551 - ~org-html-table-align-individual-fields~ ::
12553 #+vindex: org-html-table-align-individual-fields
12554 Non-~nil~ attaches style attributes for alignment to each table
12557 - ~org-html-table-caption-above~ ::
12559 #+vindex: org-html-table-caption-above
12560 Non-~nil~ places caption string at the beginning of the table.
12562 - ~org-html-table-data-tags~ ::
12564 #+vindex: org-html-table-data-tags
12565 Opening and ending tags for table data fields.
12567 - ~org-html-table-default-attributes~ ::
12569 #+vindex: org-html-table-default-attributes
12570 Default attributes and values for table tags.
12572 - ~org-html-table-header-tags~ ::
12574 #+vindex: org-html-table-header-tags
12575 Opening and ending tags for table's header fields.
12577 - ~org-html-table-row-tags~ ::
12579 #+vindex: org-html-table-row-tags
12580 Opening and ending tags for table rows.
12582 - ~org-html-table-use-header-tags-for-first-column~ ::
12584 #+vindex: org-html-table-use-header-tags-for-first-column
12585 Non-~nil~ formats column one in tables with header tags.
12587 *** Images in HTML export
12589 :DESCRIPTION: How to insert figures into HTML output.
12591 #+cindex: images, inline in HTML
12592 #+cindex: inlining images in HTML
12594 The HTML export back-end has features to convert Org image links to
12595 HTML inline images and HTML clickable image links.
12597 #+vindex: org-html-inline-images
12598 When the link in the Org file has no description, the HTML export
12599 back-end by default in-lines that image. For example:
12600 =[[file:myimg.jpg]]= is in-lined, while =[[file:myimg.jpg][the image]]= links to the text,
12601 =the image=. For more details, see the variable
12602 ~org-html-inline-images~.
12604 On the other hand, if the description part of the Org link is itself
12605 another link, such as =file:= or =http:= URL pointing to an image, the
12606 HTML export back-end in-lines this image and links to the main image.
12607 This Org syntax enables the back-end to link low-resolution thumbnail
12608 to the high-resolution version of the image, as shown in this example:
12610 : [[file:highres.jpg][file:thumb.jpg]]
12612 To change attributes of in-lined images, use =#+ATTR_HTML= lines in
12613 the Org file. This example shows realignment to right, and adds ~alt~
12614 and ~title~ attributes in support of text viewers and modern web
12615 accessibility standards.
12617 #+cindex: @samp{CAPTION}, keyword
12618 #+cindex: @samp{ATTR_HTML}, keyword
12620 ,#+CAPTION: A black cat stalking a spider
12621 ,#+ATTR_HTML: :alt cat/spider image :title Action! :align right
12625 The HTML export back-end copies the =http= links from the Org file
12628 *** Math formatting in HTML export
12630 :DESCRIPTION: Beautiful math also on the web.
12635 #+cindex: ImageMagick
12637 #+vindex: org-html-mathjax-options~
12638 LaTeX math snippets (see [[*LaTeX fragments]]) can be displayed in two
12639 different ways on HTML pages. The default is to use the [[http://www.mathjax.org][MathJax]],
12640 which should work out of the box with Org[fn:128][fn:129]. Some MathJax
12641 display options can be configured via ~org-html-mathjax-options~, or
12642 in the buffer. For example, with the following settings,
12645 ,#+HTML_MATHJAX: align: left indent: 5em tagside: left font: Neo-Euler
12646 ,#+HTML_MATHJAX: cancel.js noErrors.js
12649 #+texinfo: @noindent
12650 equation labels are displayed on the left margin and equations are
12651 five em from the left margin. In addition, it loads the two MathJax
12652 extensions =cancel.js= and =noErrors.js=[fn:130].
12654 #+vindex: org-html-mathjax-template
12655 See the docstring of ~org-html-mathjax-options~ for all supported
12656 variables. The MathJax template can be configure via
12657 ~org-html-mathjax-template~.
12659 If you prefer, you can also request that LaTeX fragments are processed
12660 into small images that will be inserted into the browser page. Before
12661 the availability of MathJax, this was the default method for Org
12662 files. This method requires that the dvipng program, dvisvgm or
12663 ImageMagick suite is available on your system. You can still get this
12666 : #+OPTIONS: tex:dvipng
12668 : #+OPTIONS: tex:dvisvgm
12670 #+texinfo: @noindent
12673 : #+OPTIONS: tex:imagemagick
12675 *** Text areas in HTML export
12677 :DESCRIPTION: An alternate way to show an example.
12680 #+cindex: text areas, in HTML
12681 Before Org mode's Babel, one popular approach to publishing code in
12682 HTML was by using =:textarea=. The advantage of this approach was
12683 that copying and pasting was built into browsers with simple
12684 JavaScript commands. Even editing before pasting was made simple.
12686 The HTML export back-end can create such text areas. It requires an
12687 =#+ATTR_HTML= line as shown in the example below with the =:textarea=
12688 option. This must be followed by either an example or a source code
12689 block. Other Org block types do not honor the =:textarea= option.
12691 By default, the HTML export back-end creates a text area 80 characters
12692 wide and height just enough to fit the content. Override these
12693 defaults with =:width= and =:height= options on the =#+ATTR_HTML=
12697 ,#+ATTR_HTML: :textarea t :width 40
12699 (defun org-xor (a b)
12707 :DESCRIPTION: Changing the appearance of the output.
12709 #+cindex: CSS, for HTML export
12710 #+cindex: HTML export, CSS
12712 #+vindex: org-export-html-todo-kwd-class-prefix
12713 #+vindex: org-export-html-tag-class-prefix
12714 You can modify the CSS style definitions for the exported file. The
12715 HTML exporter assigns the following special CSS classes[fn:131] to
12716 appropriate parts of the document---your style specifications may
12717 change these, in addition to any of the standard classes like for
12718 headlines, tables, etc.
12720 | ~p.author~ | author information, including email |
12721 | ~p.date~ | publishing date |
12722 | ~p.creator~ | creator info, about org mode version |
12723 | ~.title~ | document title |
12724 | ~.subtitle~ | document subtitle |
12725 | ~.todo~ | TODO keywords, all not-done states |
12726 | ~.done~ | the DONE keywords, all states that count as done |
12727 | ~.WAITING~ | each TODO keyword also uses a class named after itself |
12728 | ~.timestamp~ | timestamp |
12729 | ~.timestamp-kwd~ | keyword associated with a timestamp, like =SCHEDULED= |
12730 | ~.timestamp-wrapper~ | span around keyword plus timestamp |
12731 | ~.tag~ | tag in a headline |
12732 | ~._HOME~ | each tag uses itself as a class, "@" replaced by "_" |
12733 | ~.target~ | target for links |
12734 | ~.linenr~ | the line number in a code example |
12735 | ~.code-highlighted~ | for highlighting referenced code lines |
12736 | ~div.outline-N~ | div for outline level N (headline plus text) |
12737 | ~div.outline-text-N~ | extra div for text at outline level N |
12738 | ~.section-number-N~ | section number in headlines, different for each level |
12739 | ~.figure-number~ | label like "Figure 1:" |
12740 | ~.table-number~ | label like "Table 1:" |
12741 | ~.listing-number~ | label like "Listing 1:" |
12742 | ~div.figure~ | how to format an in-lined image |
12743 | ~pre.src~ | formatted source code |
12744 | ~pre.example~ | normal example |
12745 | ~p.verse~ | verse paragraph |
12746 | ~div.footnotes~ | footnote section headline |
12747 | ~p.footnote~ | footnote definition paragraph, containing a footnote |
12748 | ~.footref~ | a footnote reference number (always a <sup>) |
12749 | ~.footnum~ | footnote number in footnote definition (always <sup>) |
12750 | ~.org-svg~ | default class for a linked =.svg= image |
12752 #+vindex: org-html-style-default
12753 #+vindex: org-html-head
12754 #+vindex: org-html-head-extra
12755 #+cindex: @samp{HTML_INCLUDE_STYLE}, keyword
12756 The HTML export back-end includes a compact default style in each
12757 exported HTML file. To override the default style with another style,
12758 use these keywords in the Org file. They will replace the global
12759 defaults the HTML exporter uses.
12761 #+cindex: @samp{HTML_HEAD}, keyword
12762 #+cindex: @samp{HTML_HEAD_EXTRA}, keyword
12764 ,#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="style1.css" />
12765 ,#+HTML_HEAD_EXTRA: <link rel="alternate stylesheet" type="text/css" href="style2.css" />
12768 #+vindex: org-html-head-include-default-style
12769 To just turn off the default style, customize
12770 ~org-html-head-include-default-style~ variable, or use this option
12771 line in the Org file.
12773 #+cindex: @samp{html-style}, @samp{OPTIONS} item
12774 : #+OPTIONS: html-style:nil
12776 For longer style definitions, either use several =HTML_HEAD= and
12777 =HTML_HEAD_EXTRA= keywords, or use ~<style> ... </style>~ blocks
12778 around them. Both of these approaches can avoid referring to an
12781 #+cindex: @samp{HTML_CONTAINER_CLASS}, property
12782 #+cindex: @samp{HTML_HEADLINE_CLASS}, property
12783 In order to add styles to a sub-tree, use the =HTML_CONTAINER_CLASS=
12784 property to assign a class to the tree. In order to specify CSS
12785 styles for a particular headline, you can use the ID specified in
12786 a =CUSTOM_ID= property. You can also assign a specific class to
12787 a headline with the =HTML_HEADLINE_CLASS= property.
12789 Never change the ~org-html-style-default~ constant. Instead use other
12790 simpler ways of customizing as described above.
12792 *** JavaScript supported display of web pages
12794 :DESCRIPTION: Info and folding in a web browser.
12795 :ALT_TITLE: JavaScript support
12798 Sebastian Rose has written a JavaScript program especially designed to
12799 enhance the web viewing experience of HTML files created with Org.
12800 This program enhances large files in two different ways of viewing.
12801 One is an /Info/-like mode where each section is displayed separately
12802 and navigation can be done with the {{{kbd(n)}}} and {{{kbd(p)}}}
12803 keys, and some other keys as well, press {{{kbd(?)}}} for an overview
12804 of the available keys. The second one has a /folding/ view, much like
12805 Org provides inside Emacs. The script is available at
12806 https://orgmode.org/org-info.js and the documentation at
12807 https://orgmode.org/worg/code/org-info-js/. The script is hosted on
12808 https://orgmode.org, but for reliability, prefer installing it on your
12811 To use this program, just add this line to the Org file:
12813 #+cindex: @samp{INFOJS_OPT}, keyword
12814 : #+INFOJS_OPT: view:info toc:nil
12816 #+texinfo: @noindent
12817 The HTML header now has the code needed to automatically invoke the
12818 script. For setting options, use the syntax from the above line for
12819 options described below:
12823 The path to the script. The default is to grab the script from
12824 [[https://orgmode.org/org-info.js]], but you might want to have a local
12825 copy and use a path like =../scripts/org-info.js=.
12829 Initial view when the website is first shown. Possible values are:
12831 | =info= | Info-like interface with one section per page |
12832 | =overview= | Folding interface, initially showing only top-level |
12833 | =content= | Folding interface, starting with all headlines visible |
12834 | =showall= | Folding interface, all headlines and text visible |
12838 Maximum headline level still considered as an independent section
12839 for info and folding modes. The default is taken from
12840 ~org-export-headline-levels~, i.e., the =H= switch in =OPTIONS=. If
12841 this is smaller than in ~org-export-headline-levels~, each
12842 info/folding section can still contain child headlines.
12846 Should the table of contents /initially/ be visible? Even when
12847 =nil=, you can always get to the "toc" with {{{kbd(i)}}}.
12851 The depth of the table of contents. The defaults are taken from the
12852 variables ~org-export-headline-levels~ and ~org-export-with-toc~.
12856 Does the CSS of the page specify a fixed position for the "toc"? If
12857 yes, the toc is displayed as a section.
12861 Should there be short contents (children) in each section? Make
12862 this =above= if the section should be above initial text.
12866 Headings are highlighted when the mouse is over them. Should be
12867 =underline= (default) or a background color like =#cccccc=.
12871 Should view-toggle buttons be everywhere? When =nil= (the default),
12872 only one such button is present.
12874 #+vindex: org-infojs-options
12875 #+vindex: org-export-html-use-infojs
12876 You can choose default values for these options by customizing the
12877 variable ~org-infojs-options~. If you always want to apply the script
12878 to your pages, configure the variable ~org-export-html-use-infojs~.
12882 :DESCRIPTION: Exporting to @LaTeX{} and processing to PDF.
12884 #+cindex: @LaTeX{} export
12885 #+cindex: PDF export
12887 The LaTeX export back-end can handle complex documents, incorporate
12888 standard or custom LaTeX document classes, generate documents using
12889 alternate LaTeX engines, and produce fully linked PDF files with
12890 indexes, bibliographies, and tables of contents, destined for
12891 interactive online viewing or high-quality print publication.
12893 While the details are covered in-depth in this section, here are some
12894 quick references to variables for the impatient: for engines, see
12895 ~org-latex-compiler~; for build sequences, see
12896 ~org-latex-pdf-process~; for packages, see
12897 ~org-latex-default-packages-alist~ and ~org-latex-packages-alist~.
12899 An important note about the LaTeX export back-end: it is sensitive to
12900 blank lines in the Org document. That's because LaTeX itself depends
12901 on blank lines to tell apart syntactical elements, such as paragraphs.
12903 *** LaTeX/PDF export commands
12905 :DESCRIPTION: For producing @LaTeX{} and PDF documents.
12908 - {{{kbd(C-c C-e l l)}}} (~org-latex-export-to-latex~) ::
12910 #+kindex: C-c C-e l l
12911 #+findex: org-latex-export-to-latex~
12912 Export to a LaTeX file with a =.tex= extension. For =myfile.org=,
12913 Org exports to =myfile.tex=, overwriting without warning.
12915 - {{{kbd(C-c C-e l L)}}} (~org-latex-export-as-latex~) ::
12917 #+kindex: C-c C-e l L
12918 #+findex: org-latex-export-as-latex
12919 Export to a temporary buffer. Do not create a file.
12921 - {{{kbd(C-c C-e l p)}}} (~org-latex-export-to-pdf~) ::
12923 #+kindex: C-c C-e l p
12924 #+findex: org-latex-export-to-pdf
12925 Export as LaTeX file and convert it to PDF file.
12927 - {{{kbd(C-c C-e l o)}}} ::
12929 #+kindex: C-c C-e l o
12930 Export as LaTeX file and convert it to PDF, then open the PDF using
12931 the default viewer.
12933 - {{{kbd(M-x org-export-region-as-latex)}}} ::
12935 Convert the region to LaTeX under the assumption that it was in Org
12936 mode syntax before. This is a global command that can be invoked in
12939 #+vindex: org-latex-compiler
12940 #+vindex: org-latex-bibtex-compiler
12941 #+vindex: org-latex-default-packages-alist
12945 #+cindex: @samp{LATEX_COMPILER}, keyword
12946 The LaTeX export back-end can use any of these LaTeX engines:
12947 =pdflatex=, =xelatex=, and =lualatex=. These engines compile LaTeX
12948 files with different compilers, packages, and output options. The
12949 LaTeX export back-end finds the compiler version to use from
12950 ~org-latex-compiler~ variable or the =#+LATEX_COMPILER= keyword in the
12951 Org file. See the docstring for the
12952 ~org-latex-default-packages-alist~ for loading packages with certain
12953 compilers. Also see ~org-latex-bibtex-compiler~ to set the
12954 bibliography compiler[fn:132].
12956 *** LaTeX specific export settings
12958 :DESCRIPTION: Unique to this @LaTeX{} back-end.
12961 The LaTeX export back-end has several additional keywords for
12962 customizing LaTeX output. Setting these keywords works similar to the
12963 general options (see [[*Export Settings]]).
12965 #+attr_texinfo: :sep ,
12967 #+cindex: @samp{DESCRIPTION}, keyword
12968 #+vindex: org-latex-hyperref-template
12969 #+vindex: org-latex-title-command
12970 The document's description. The description along with author name,
12971 keywords, and related file metadata are inserted in the output file
12972 by the hyperref package. See ~org-latex-hyperref-template~ for
12973 customizing metadata items. See ~org-latex-title-command~ for
12974 typesetting description into the document's front matter. Use
12975 multiple =DESCRIPTION= keywords for long descriptions.
12978 #+cindex: @samp{LANGUAGE}, keyword
12979 #+vindex: org-latex-package-alist
12980 In order to be effective, the =babel= or =polyglossia=
12981 packages---according to the LaTeX compiler used---must be loaded
12982 with the appropriate language as argument. This can be accomplished
12983 by modifying the =org-latex-package-alist= variable, e.g., with the
12986 #+begin_src emacs-lisp
12987 (add-to-list org-latex-package-alist
12988 '("AUTO" "babel" t ("pdflatex")))
12989 (add-to-list org-latex-package-alist
12990 '("AUTO" "polyglossia" t ("xelatex" "lualatex")))
12995 #+cindex: @samp{LATEX_CLASS}, keyword
12996 #+vindex: org-latex-default-class
12997 #+vindex: org-latex-classes
12998 This is LaTeX document class, such as /article/, /report/, /book/,
12999 and so on, which contain predefined preamble and headline level
13000 mapping that the LaTeX export back-end needs. The back-end reads
13001 the default class name from the ~org-latex-default-class~ variable.
13002 Org has /article/ as the default class. A valid default class must
13003 be an element of ~org-latex-classes~.
13005 - =LATEX_CLASS_OPTIONS= ::
13007 #+cindex: @samp{LATEX_CLASS_OPTIONS}, keyword
13008 Options the LaTeX export back-end uses when calling the LaTeX
13011 - =LATEX_COMPILER= ::
13013 #+cindex: @samp{LATEX_COMPILER}, keyword
13014 #+vindex: org-latex-compiler
13015 The compiler, such as =pdflatex=, =xelatex=, =lualatex=, for
13016 producing the PDF. See ~org-latex-compiler~.
13018 - =LATEX_HEADER=, =LATEX_HEADER_EXTRA= ::
13020 #+cindex: @samp{LATEX_HEADER}, keyword
13021 #+cindex: @samp{LATEX_HEADER_EXTRA}, keyword
13022 #+vindex: org-latex-classes
13023 Arbitrary lines to add to the document's preamble, before the
13024 hyperref settings. See ~org-latex-classes~ for adjusting the
13025 structure and order of the LaTeX headers.
13029 #+cindex: @samp{KEYWORDS}, keyword
13030 #+vindex: org-latex-hyperref-template
13031 #+vindex: org-latex-title-command
13032 The keywords for the document. The description along with author
13033 name, keywords, and related file metadata are inserted in the output
13034 file by the hyperref package. See ~org-latex-hyperref-template~ for
13035 customizing metadata items. See ~org-latex-title-command~ for
13036 typesetting description into the document's front matter. Use
13037 multiple =KEYWORDS= lines if necessary.
13041 #+cindex: @samp{SUBTITLE}, keyword
13042 #+vindex: org-latex-subtitle-separate
13043 #+vindex: org-latex-subtitle-format
13044 The document's subtitle. It is typeset as per
13045 ~org-latex-subtitle-format~. If ~org-latex-subtitle-separate~ is
13046 non-~nil~, it is typed as part of the ~\title~ macro. See
13047 ~org-latex-hyperref-template~ for customizing metadata items. See
13048 ~org-latex-title-command~ for typesetting description into the
13049 document's front matter.
13051 The following sections have further details.
13053 *** LaTeX header and sectioning structure
13055 :DESCRIPTION: Setting up the export file structure.
13056 :ALT_TITLE: LaTeX header and sectioning
13058 #+cindex: @LaTeX{} class
13059 #+cindex: @LaTeX{} sectioning structure
13060 #+cindex: @LaTeX{} header
13061 #+cindex: header, for @LaTeX{} files
13062 #+cindex: sectioning structure, for @LaTeX{} export
13064 The LaTeX export back-end converts the first three of Org's outline
13065 levels into LaTeX headlines. The remaining Org levels are exported as
13066 lists. To change this globally for the cut-off point between levels
13067 and lists, (see [[*Export Settings]]).
13069 By default, the LaTeX export back-end uses the /article/ class.
13071 #+vindex: org-latex-default-class
13072 #+vindex: org-latex-classes
13073 #+vindex: org-latex-default-packages-alist
13074 #+vindex: org-latex-packages-alist
13075 To change the default class globally, edit ~org-latex-default-class~.
13076 To change the default class locally in an Org file, add option lines
13077 =#+LATEX_CLASS: myclass=. To change the default class for just a part
13078 of the Org file, set a sub-tree property, =EXPORT_LATEX_CLASS=. The
13079 class name entered here must be valid member of ~org-latex-classes~.
13080 This variable defines a header template for each class into which the
13081 exporter splices the values of ~org-latex-default-packages-alist~ and
13082 ~org-latex-packages-alist~. Use the same three variables to define
13083 custom sectioning or custom classes.
13085 #+cindex: @samp{LATEX_CLASS}, keyword
13086 #+cindex: @samp{LATEX_CLASS_OPTIONS}, keyword
13087 #+cindex: @samp{EXPORT_LATEX_CLASS}, property
13088 #+cindex: @samp{EXPORT_LATEX_CLASS_OPTIONS}, property
13089 The LaTeX export back-end sends the =LATEX_CLASS_OPTIONS= keyword and
13090 =EXPORT_LATEX_CLASS_OPTIONS= property as options to the LaTeX
13091 ~\documentclass~ macro. The options and the syntax for specifying
13092 them, including enclosing them in square brackets, follow LaTeX
13095 : #+LATEX_CLASS_OPTIONS: [a4paper,11pt,twoside,twocolumn]
13097 #+cindex: @samp{LATEX_HEADER}, keyword
13098 #+cindex: @samp{LATEX_HEADER_EXTRA}, keyword
13099 The LaTeX export back-end appends values from =LATEX_HEADER= and
13100 =LATEX_HEADER_EXTRA= keywords to the LaTeX header. The docstring for
13101 ~org-latex-classes~ explains in more detail. Also note that LaTeX
13102 export back-end does not append =LATEX_HEADER_EXTRA= to the header
13103 when previewing LaTeX snippets (see [[*Previewing LaTeX fragments]]).
13105 A sample Org file with the above headers:
13108 ,#+LATEX_CLASS: article
13109 ,#+LATEX_CLASS_OPTIONS: [a4paper]
13110 ,#+LATEX_HEADER: \usepackage{xyz}
13118 *** Quoting LaTeX code
13120 :DESCRIPTION: Incorporating literal @LaTeX{} code.
13123 The LaTeX export back-end can insert any arbitrary LaTeX code, see
13124 [[*Embedded LaTeX]]. There are three ways to embed such code in the Org
13125 file and they all use different quoting syntax.
13127 #+cindex: inline, in @LaTeX{} export
13128 Inserting in-line quoted with @ symbols:
13130 : Code embedded in-line @@latex:any arbitrary LaTeX code@@ in a paragraph.
13132 #+cindex: @samp{LATEX}, keyword
13133 Inserting as one or more keyword lines in the Org file:
13135 : #+LATEX: any arbitrary LaTeX code
13137 #+cindex: @samp{BEGIN_EXPORT latex}
13138 Inserting as an export block in the Org file, where the back-end
13139 exports any code between begin and end markers:
13142 ,#+BEGIN_EXPORT latex
13143 any arbitrary LaTeX code
13147 *** Tables in LaTeX export
13149 :DESCRIPTION: Options for exporting tables to @LaTeX{}.
13151 #+cindex: tables, in @LaTeX{} export
13153 The LaTeX export back-end can pass several LaTeX attributes for table
13154 contents and layout. Besides specifying a label (see [[*Internal Links]])
13155 and a caption (see [[*Captions]]), the other valid LaTeX attributes
13158 #+attr_texinfo: :sep ,
13161 #+vindex: org-latex-default-table-mode
13162 The LaTeX export back-end wraps the table differently depending on
13163 the mode for accurate rendering of math symbols. Mode is either
13164 =table=, =math=, =inline-math= or =verbatim=.
13166 For =math= or =inline-math= mode, LaTeX export back-end wraps the
13167 table in a math environment, but every cell in it is exported as-is.
13168 The LaTeX export back-end determines the default mode from
13169 ~org-latex-default-table-mode~. The LaTeX export back-end merges
13170 contiguous tables in the same mode into a single environment.
13172 - =:environment= ::
13174 #+vindex: org-latex-default-table-environment
13175 Set the default LaTeX table environment for the LaTeX export
13176 back-end to use when exporting Org tables. Common LaTeX table
13177 environments are provided by these packages: tabularx, longtable,
13178 array, tabu, and bmatrix. For packages, such as tabularx and tabu,
13179 or any newer replacements, include them in the
13180 ~org-latex-packages-alist~ variable so the LaTeX export back-end can
13181 insert the appropriate load package headers in the converted LaTeX
13182 file. Look in the docstring for the ~org-latex-packages-alist~
13183 variable for configuring these packages for LaTeX snippet previews,
13188 Use =CAPTION= keyword to set a simple caption for a table (see
13189 [[*Captions]]). For custom captions, use =:caption= attribute, which
13190 accepts raw LaTeX code. =:caption= value overrides =CAPTION= value.
13192 - =:float=, =:placement= ::
13194 The table environments by default are not floats in LaTeX. To make
13195 them floating objects use =:float= with one of the following
13196 options: =sideways=, =multicolumn=, =t=, and =nil=.
13198 LaTeX floats can also have additional layout =:placement=
13199 attributes. These are the usual =[h t b p ! H]= permissions
13200 specified in square brackets. Note that for =:float sideways=
13201 tables, the LaTeX export back-end ignores =:placement= attributes.
13203 - =:align=, =:font=, =:width= ::
13205 The LaTeX export back-end uses these attributes for regular tables
13206 to set their alignments, fonts, and widths.
13210 When =:spread= is non-~nil~, the LaTeX export back-end spreads or
13211 shrinks the table by the =:width= for tabu and longtabu
13212 environments. =:spread= has no effect if =:width= is not set.
13214 - =:booktabs=, =:center=, =:rmlines= ::
13216 #+vindex: org-latex-tables-booktabs
13217 #+vindex: org-latex-tables-centered
13218 All three commands are toggles. =:booktabs= brings in modern
13219 typesetting enhancements to regular tables. The booktabs package
13220 has to be loaded through ~org-latex-packages-alist~. =:center= is
13221 for centering the table. =:rmlines= removes all but the very first
13222 horizontal line made of ASCII characters from "table.el" tables
13225 - =:math-prefix=, =:math-suffix=, =:math-arguments= ::
13227 The LaTeX export back-end inserts =:math-prefix= string value in
13228 a math environment before the table. The LaTeX export back-end
13229 inserts =:math-suffix= string value in a math environment after the
13230 table. The LaTeX export back-end inserts =:math-arguments= string
13231 value between the macro name and the table's contents.
13232 =:math-arguments= comes in use for matrix macros that require more
13233 than one argument, such as =qbordermatrix=.
13235 LaTeX table attributes help formatting tables for a wide range of
13236 situations, such as matrix product or spanning multiple pages:
13239 ,#+ATTR_LATEX: :environment longtable :align l|lp{3cm}r|l
13243 ,#+ATTR_LATEX: :mode math :environment bmatrix :math-suffix \times
13246 ,#+ATTR_LATEX: :mode math :environment bmatrix
13251 Set the caption with the LaTeX command
13252 =\bicaption{HeadingA}{HeadingB}=:
13255 ,#+ATTR_LATEX: :caption \bicaption{HeadingA}{HeadingB}
13260 *** Images in LaTeX export
13262 :DESCRIPTION: How to insert figures into @LaTeX{} output.
13264 #+cindex: images, inline in LaTeX
13265 #+cindex: inlining images in LaTeX
13266 #+cindex: @samp{ATTR_LATEX}, keyword
13268 The LaTeX export back-end processes image links in Org files that do
13269 not have descriptions, such as these links =[[file:img.jpg]]= or
13270 =[[./img.jpg]]=, as direct image insertions in the final PDF output. In
13271 the PDF, they are no longer links but actual images embedded on the
13272 page. The LaTeX export back-end uses =\includegraphics= macro to
13273 insert the image. But for TikZ (http://sourceforge.net/projects/pgf/)
13274 images, the back-end uses an ~\input~ macro wrapped within
13275 a ~tikzpicture~ environment.
13277 For specifying image =:width=, =:height=, and other =:options=, use
13281 ,#+ATTR_LATEX: :width 5cm :options angle=90
13282 [[./img/sed-hr4049.pdf]]
13285 For custom commands for captions, use the =:caption= attribute. It
13286 overrides the default =#+CAPTION= value:
13289 ,#+ATTR_LATEX: :caption \bicaption{HeadingA}{HeadingB}
13290 [[./img/sed-hr4049.pdf]]
13293 When captions follow the method as described in [[*Captions]], the LaTeX
13294 export back-end wraps the picture in a floating =figure= environment.
13295 To float an image without specifying a caption, set the =:float=
13296 attribute to one of the following:
13300 For a standard =figure= environment; used by default whenever an
13301 image has a caption.
13305 To span the image across multiple columns of a page; the back-end
13306 wraps the image in a =figure*= environment.
13310 For text to flow around the image on the right; the figure occupies
13311 the left half of the page.
13315 For a new page with the image sideways, rotated ninety degrees, in
13316 a =sidewaysfigure= environment; overrides =:placement= setting.
13320 To avoid a =:float= even if using a caption.
13322 Use the =placement= attribute to modify a floating environment's
13326 ,#+ATTR_LATEX: :float wrap :width 0.38\textwidth :placement {r}{0.4\textwidth}
13330 #+vindex: org-latex-images-centered
13331 #+cindex: center image in LaTeX export
13332 #+cindex: image, centering in LaTeX export
13333 The LaTeX export back-end centers all images by default. Setting
13334 =:center= to =nil= disables centering. To disable centering globally,
13335 set ~org-latex-images-centered~ to =t=.
13337 Set the =:comment-include= attribute to non-~nil~ value for the LaTeX
13338 export back-end to comment out the =\includegraphics= macro.
13340 *** Plain lists in LaTeX export
13342 :DESCRIPTION: Attributes specific to lists.
13345 #+cindex: plain lists, in @LaTeX{} export
13346 #+cindex: @samp{ATTR_LATEX}, keyword
13347 The LaTeX export back-end accepts the =environment= and =options=
13348 attributes for plain lists. Both attributes work together for
13349 customizing lists, as shown in the examples:
13352 ,#+LATEX_HEADER: \usepackage[inline]{enumitem}
13353 Some ways to say "Hello":
13354 ,#+ATTR_LATEX: :environment itemize*
13355 ,#+ATTR_LATEX: :options [label={}, itemjoin={,}, itemjoin*={, and}]
13361 Since LaTeX supports only four levels of nesting for lists, use an
13362 external package, such as =enumitem= in LaTeX, for levels deeper than
13366 ,#+LATEX_HEADER: \usepackage{enumitem}
13367 ,#+LATEX_HEADER: \renewlist{itemize}{itemize}{9}
13368 ,#+LATEX_HEADER: \setlist[itemize]{label=$\circ$}
13376 *** Source blocks in LaTeX export
13378 :DESCRIPTION: Attributes specific to source code blocks.
13380 #+cindex: source blocks, in @LaTeX{} export
13381 #+cindex: @samp{ATTR_LATEX}, keyword
13383 The LaTeX export back-end can make source code blocks into floating
13384 objects through the attributes =:float= and =:options=. For =:float=:
13388 Makes a source block float; by default floats any source block with
13393 Spans the source block across multiple columns of a page.
13397 Avoids a =:float= even if using a caption; useful for source code
13398 blocks that may not fit on a page.
13401 ,#+ATTR_LATEX: :float nil
13402 ,#+BEGIN_SRC emacs-lisp
13403 Lisp code that may not fit in a single page.
13407 #+vindex: org-latex-listings-options
13408 #+vindex: org-latex-minted-options
13409 The LaTeX export back-end passes string values in =:options= to LaTeX
13410 packages for customization of that specific source block. In the
13411 example below, the =:options= are set for Minted. Minted is a source
13412 code highlighting LaTeX package with many configurable options.
13415 ,#+ATTR_LATEX: :options commentstyle=\bfseries
13416 ,#+BEGIN_SRC emacs-lisp
13418 (if (< n 2) n (+ (Fib (- n 1)) (Fib (- n 2)))))
13422 To apply similar configuration options for all source blocks in
13423 a file, use the ~org-latex-listings-options~ and
13424 ~org-latex-minted-options~ variables.
13426 *** Example blocks in LaTeX export
13428 :DESCRIPTION: Attributes specific to example blocks.
13430 #+cindex: example blocks, in @LaTeX{} export
13431 #+cindex: verbatim blocks, in @LaTeX{} export
13432 #+cindex: @samp{ATTR_LATEX}, keyword
13434 The LaTeX export back-end wraps the contents of example blocks in
13435 a =verbatim= environment. To change this behavior to use another
13436 environment globally, specify an appropriate export filter (see
13437 [[*Advanced Export Configuration]]). To change this behavior to use
13438 another environment for each block, use the =:environment= parameter
13439 to specify a custom environment.
13442 ,#+ATTR_LATEX: :environment myverbatim
13444 This sentence is false.
13448 *** Special blocks in LaTeX export
13450 :DESCRIPTION: Attributes specific to special blocks.
13453 #+cindex: special blocks, in @LaTeX{} export
13454 #+cindex: abstract, in @LaTeX{} export
13455 #+cindex: proof, in @LaTeX{} export
13456 #+cindex: @samp{ATTR_LATEX}, keyword
13458 For other special blocks in the Org file, the LaTeX export back-end
13459 makes a special environment of the same name. The back-end also takes
13460 =:options=, if any, and appends as-is to that environment's opening
13461 string. For example:
13465 We demonstrate how to solve the Syracuse problem.
13468 ,#+ATTR_LATEX: :options [Proof of important theorem]
13471 Therefore, any even number greater than 2 is the sum of two primes.
13475 #+texinfo: @noindent
13480 We demonstrate how to solve the Syracuse problem.
13483 \begin{proof}[Proof of important theorem]
13485 Therefore, any even number greater than 2 is the sum of two primes.
13489 If you need to insert a specific caption command, use =:caption=
13490 attribute. It overrides standard =CAPTION= value, if any. For
13494 ,#+ATTR_LATEX: :caption \MyCaption{HeadingA}
13500 *** Horizontal rules in LaTeX export
13502 :DESCRIPTION: Attributes specific to horizontal rules.
13504 #+cindex: horizontal rules, in @LaTeX{} export
13505 #+cindex: @samp{ATTR_LATEX}, keyword
13507 The LaTeX export back-end converts horizontal rules by the specified
13508 =:width= and =:thickness= attributes. For example:
13511 ,#+ATTR_LATEX: :width .6\textwidth :thickness 0.8pt
13517 :DESCRIPTION: Exporting to Markdown.
13519 #+cindex: Markdown export
13521 The Markdown export back-end, "md", converts an Org file to Markdown
13522 format, as defined at http://daringfireball.net/projects/markdown/.
13524 Since it is built on top of the HTML back-end (see [[*HTML Export]]), it
13525 converts every Org construct not defined in Markdown syntax, such as
13528 *** Markdown export commands
13533 - {{{kbd(C-c C-e m m)}}} (~org-md-export-to-markdown~) ::
13535 #+kindex: C-c C-c m m
13536 #+findex: org-md-export-to-markdown
13537 Export to a text file with Markdown syntax. For =myfile.org=, Org
13538 exports to =myfile.md=, overwritten without warning.
13540 - {{{kbd(C-c C-e m M)}}} (~org-md-export-as-markdown~) ::
13542 #+kindex: C-c C-c m M
13543 #+findex: org-md-export-as-markdown
13544 Export to a temporary buffer. Does not create a file.
13546 - {{{kbd(C-c C-e m o)}}} ::
13548 #+kindex: C-c C-e m o
13549 Export as a text file with Markdown syntax, then open it.
13551 *** Header and sectioning structure
13556 #+vindex: org-md-headline-style
13557 Based on ~org-md-headline-style~, Markdown export can generate
13558 headlines of both /atx/ and /setext/ types. /atx/ limits headline
13559 levels to two whereas /setext/ limits headline levels to six. Beyond
13560 these limits, the export back-end converts headlines to lists. To set
13561 a limit to a level before the absolute limit (see [[*Export Settings]]).
13563 ** OpenDocument Text Export
13565 :DESCRIPTION: Exporting to OpenDocument Text.
13568 #+cindex: OpenDocument
13569 #+cindex: export, OpenDocument
13570 #+cindex: LibreOffice
13572 The ODT export back-end handles creating of OpenDocument Text (ODT)
13573 format. Documents created by this exporter use the
13574 {{{cite(OpenDocument-v1.2 specification)}}}[fn:133] and are compatible
13575 with LibreOffice 3.4.
13577 *** Pre-requisites for ODT export
13579 :DESCRIPTION: Required packages.
13583 The ODT export back-end relies on the zip program to create the final
13584 compressed ODT output. Check if =zip= is locally available and
13585 executable. Without it, export cannot finish.
13587 *** ODT export commands
13589 :DESCRIPTION: Invoking export.
13592 - {{{kbd(C-c C-e o o)}}} (~org-export-to-odt~) ::
13594 #+kindex: C-c C-e o o
13595 #+findex: org-export-to-odt
13596 Export as OpenDocument Text file.
13598 #+cindex: @samp{EXPORT_FILE_NAME}, property
13599 #+vindex: org-odt-preferred-output-format
13601 If ~org-odt-preferred-output-format~ is specified, the ODT export
13602 back-end automatically converts the exported file to that format.
13604 For =myfile.org=, Org exports to =myfile.odt=, overwriting without
13605 warning. The ODT export back-end exports a region only if a region
13608 If the selected region is a single tree, the ODT export back-end
13609 makes the tree head the document title. Incidentally, {{{kbd(C-c
13610 @)}}} selects the current sub-tree. If the tree head entry has, or
13611 inherits, an =EXPORT_FILE_NAME= property, the ODT export back-end
13612 uses that for file name.
13614 - {{{kbd(C-c C-e o O)}}} ::
13616 #+kindex: C-c C-e o O
13617 Export as an OpenDocument Text file and open the resulting file.
13619 #+vindex: org-export-odt-preferred-output-format
13620 If ~org-export-odt-preferred-output-format~ is specified, open the
13621 converted file instead. See [[*Automatically exporting to other
13624 *** ODT specific export settings
13626 :DESCRIPTION: Configuration options.
13629 The ODT export back-end has several additional keywords for
13630 customizing ODT output. Setting these keywords works similar to the
13631 general options (see [[*Export Settings]]).
13635 #+cindex: @samp{DESCRIPTION}, keyword
13636 This is the document's description, which the ODT export back-end
13637 inserts as document metadata. For long descriptions, use multiple
13638 lines, prefixed with =DESCRIPTION=.
13642 #+cindex: @samp{KEYWORDS}, keyword
13643 The keywords for the document. The ODT export back-end inserts the
13644 description along with author name, keywords, and related file
13645 metadata as metadata in the output file. Use multiple =KEYWORDS= if
13648 - =ODT_STYLES_FILE= ::
13650 #+cindex: @samp{ODT_STYLES_FILE}, keyword
13651 #+vindex: org-odt-styles-file
13652 The ODT export back-end uses the ~org-odt-styles-file~ by default.
13653 See [[*Applying custom styles]] for details.
13657 #+cindex: @samp{SUBTITLE}, keyword
13658 The document subtitle.
13660 *** Extending ODT export
13662 :DESCRIPTION: Producing DOC, PDF files.
13665 The ODT export back-end can produce documents in other formats besides
13666 ODT using a specialized ODT converter process. Its common interface
13667 works with popular converters to produce formats such as =doc=, or
13668 convert a document from one format, say =csv=, to another format, say
13671 #+cindex: @file{unoconv}
13672 #+vindex: org-odt-convert-process
13673 Customize ~org-odt-convert-process~ variable to point to =unoconv=,
13674 which is the ODT's preferred converter. Working installations of
13675 LibreOffice would already have =unoconv= installed. Alternatively,
13676 other converters may be substituted here. See [[*Configuring
13677 a document converter]].
13679 **** Automatically exporting to other formats
13684 #+vindex: org-odt-preferred-output-format
13685 If ODT format is just an intermediate step to get to other formats,
13686 such as =doc=, =docx=, =rtf=, or =pdf=, etc., then extend the ODT
13687 export back-end to directly produce that format. Specify the final
13688 format in the ~org-odt-preferred-output-format~ variable. This is one
13689 way to extend (see [[*ODT export commands]]).
13691 **** Converting between document formats
13696 The Org export back-end is made to be inter-operable with a wide range
13697 of text document format converters. Newer generation converters, such
13698 as LibreOffice and Pandoc, can handle hundreds of formats at once.
13699 Org provides a consistent interaction with whatever converter is
13700 installed. Here are some generic commands:
13702 - {{{kbd(M-x org-odt-convert)}}} ::
13704 #+findex: org-odt-convert
13705 Convert an existing document from one format to another. With
13706 a prefix argument, opens the newly produced file.
13708 *** Applying custom styles
13710 :DESCRIPTION: Styling the output.
13712 #+cindex: styles, custom
13713 #+cindex: template, custom
13715 The ODT export back-end comes with many OpenDocument styles (see
13716 [[*Working with OpenDocument style files]]). To expand or further
13717 customize these built-in style sheets, either edit the style sheets
13718 directly or generate them using an application such as LibreOffice.
13719 The example here shows creating a style using LibreOffice.
13721 **** Applying custom styles: the easy way
13726 1. Create a sample =example.org= file with settings as shown below,
13727 and export it to ODT format.
13729 : #+OPTIONS: H:10 num:t
13731 2. Open the above =example.odt= using LibreOffice. Use the /Stylist/
13732 to locate the target styles, which typically have the "Org" prefix.
13733 Open one, modify, and save as either OpenDocument Text (ODT) or
13734 OpenDocument Template (OTT) file.
13737 #+vindex: org-odt-styles-file
13738 Customize the variable ~org-odt-styles-file~ and point it to the
13739 newly created file. For additional configuration options, see
13740 [[x-overriding-factory-styles][Overriding factory styles]].
13742 #+cindex: @samp{ODT_STYLES_FILE}, keyword
13743 To apply an ODT style to a particular file, use the
13744 =ODT_STYLES_FILE= keyword as shown in the example below:
13746 : #+ODT_STYLES_FILE: "/path/to/example.ott"
13748 #+texinfo: @noindent
13751 : #+ODT_STYLES_FILE: ("/path/to/file.ott" ("styles.xml" "image/hdr.png"))
13753 **** Using third-party styles and templates
13758 The ODT export back-end relies on many templates and style names.
13759 Using third-party styles and templates can lead to mismatches.
13760 Templates derived from built in ODT templates and styles seem to have
13763 *** Links in ODT export
13765 :DESCRIPTION: Handling and formatting links.
13767 #+cindex: links, in ODT export
13769 ODT exporter creates native cross-references for internal links. It
13770 creates Internet-style links for all other links.
13772 A link with no description and pointing to a regular, un-itemized,
13773 outline heading is replaced with a cross-reference and section number
13776 A =\ref{label}=-style reference to an image, table etc., is replaced
13777 with a cross-reference and sequence number of the labeled entity. See
13778 [[*Labels and captions in ODT export]].
13780 *** Tables in ODT export
13782 :DESCRIPTION: Org tables conversions.
13785 #+cindex: tables, in ODT export
13787 The ODT export back-end handles native Org mode tables (see [[*Tables]])
13788 and simple =table.el= tables. Complex =table.el= tables having column
13789 or row spans are not supported. Such tables are stripped from the
13792 By default, the ODT export back-end exports a table with top and
13793 bottom frames and with ruled lines separating row and column groups
13794 (see [[*Column Groups]]). All tables are typeset to occupy the same
13795 width. The ODT export back-end honors any table alignments and
13796 relative widths for columns (see [[*Column Width and Alignment]]).
13798 Note that the ODT export back-end interprets column widths as weighted
13799 ratios, the default weight being 1.
13801 #+cindex: @samp{ATTR_ODT}, keyword
13802 Specifying =:rel-width= property on an =ATTR_ODT= line controls the
13803 width of the table. For example:
13806 ,#+ATTR_ODT: :rel-width 50
13807 | Area/Month | Jan | Feb | Mar | Sum |
13808 |---------------+-------+-------+-------+-------|
13810 | <l13> | <r5> | <r5> | <r5> | <r6> |
13811 | North America | 1 | 21 | 926 | 948 |
13812 | Middle East | 6 | 75 | 844 | 925 |
13813 | Asia Pacific | 9 | 27 | 790 | 826 |
13814 |---------------+-------+-------+-------+-------|
13815 | Sum | 16 | 123 | 2560 | 2699 |
13818 On export, the above table takes 50% of text width area. The exporter
13819 sizes the columns in the ratio: 13:5:5:5:6. The first column is
13820 left-aligned and rest of the columns, right-aligned. Vertical rules
13821 separate the header and the last column. Horizontal rules separate
13822 the header and the last row.
13824 For even more customization, create custom table styles and associate
13825 them with a table using the =ATTR_ODT= keyword. See [[*Customizing
13826 tables in ODT export]].
13828 *** Images in ODT export
13830 :DESCRIPTION: Inserting images.
13832 #+cindex: images, embedding in ODT
13833 #+cindex: embedding images in ODT
13835 **** Embedding images
13840 The ODT export back-end processes image links in Org files that do not
13841 have descriptions, such as these links =[[file:img.jpg]]= or =[[./img.jpg]]=,
13842 as direct image insertions in the final output. Either of these
13849 **** Embedding clickable images
13854 For clickable images, provide a link whose description is another link
13855 to an image file. For example, to embed an image
13856 =org-mode-unicorn.png= which when clicked jumps to https://orgmode.org
13857 website, do the following
13859 : [[https://orgmode.org][./org-mode-unicorn.png]]
13861 **** Sizing and scaling of embedded images
13866 #+cindex: @samp{ATTR_ODT}, keyword
13868 Control the size and scale of the embedded images with the =ATTR_ODT=
13871 #+cindex: identify, ImageMagick
13872 #+vindex: org-odt-pixels-per-inch
13873 The ODT export back-end starts with establishing the size of the image
13874 in the final document. The dimensions of this size are measured in
13875 centimeters. The back-end then queries the image file for its
13876 dimensions measured in pixels. For this measurement, the back-end
13877 relies on ImageMagick's identify program or Emacs ~create-image~ and
13878 ~image-size~ API. ImageMagick is the preferred choice for large file
13879 sizes or frequent batch operations. The back-end then converts the
13880 pixel dimensions using ~org-odt-pixels-per-inch~ into the familiar 72
13881 dpi or 96 dpi. The default value for this is in
13882 ~display-pixels-per-inch~, which can be tweaked for better results
13883 based on the capabilities of the output device. Here are some common
13884 image scaling operations:
13886 - Explicitly size the image ::
13888 To embed =img.png= as a 10 cm x 10 cm image, do the following:
13891 ,#+ATTR_ODT: :width 10 :height 10
13895 - Scale the image ::
13897 To embed =img.png= at half its size, do the following:
13900 ,#+ATTR_ODT: :scale 0.5
13904 - Scale the image to a specific width ::
13906 To embed =img.png= with a width of 10 cm while retaining the
13907 original height:width ratio, do the following:
13910 ,#+ATTR_ODT: :width 10
13914 - Scale the image to a specific height ::
13916 To embed =img.png= with a height of 10 cm while retaining the
13917 original height:width ratio, do the following:
13920 ,#+ATTR_ODT: :height 10
13924 **** Anchoring of images
13929 #+cindex: @samp{ATTR_ODT}, keyword
13930 The ODT export back-end can anchor images to =as-char=, =paragraph=,
13931 or =page=. Set the preferred anchor using the =:anchor= property of
13932 the =ATTR_ODT= line.
13934 To create an image that is anchored to a page:
13937 ,#+ATTR_ODT: :anchor page
13941 *** Math formatting in ODT export
13943 :DESCRIPTION: Formatting @LaTeX{} fragments.
13946 The ODT exporter has special support for handling math.
13948 **** LaTeX math snippets
13950 :DESCRIPTION: Embedding in @LaTeX{} format.
13953 LaTeX math snippets (see [[*LaTeX fragments]]) can be embedded in the ODT
13954 document in one of the following ways:
13959 Add this line to the Org file. This option is activated on
13964 With this option, LaTeX fragments are first converted into MathML
13965 fragments using an external LaTeX-to-MathML converter program. The
13966 resulting MathML fragments are then embedded as an OpenDocument
13967 Formula in the exported document.
13969 #+vindex: org-latex-to-mathml-convert-command
13970 #+vindex: org-latex-to-mathml-jar-file
13971 You can specify the LaTeX-to-MathML converter by customizing the
13972 variables ~org-latex-to-mathml-convert-command~ and
13973 ~org-latex-to-mathml-jar-file~.
13975 If you prefer to use MathToWeb[fn:134] as your converter, you can
13976 configure the above variables as shown below.
13978 #+begin_src emacs-lisp
13979 (setq org-latex-to-mathml-convert-command
13980 "java -jar %j -unicode -force -df %o %I"
13981 org-latex-to-mathml-jar-file
13982 "/path/to/mathtoweb.jar")
13985 #+texinfo: @noindent
13986 or, to use LaTeX​ML[fn:135] instead,
13988 #+begin_src emacs-lisp
13989 (setq org-latex-to-mathml-convert-command
13990 "latexmlmath \"%i\" --presentationmathml=%o")
13993 To quickly verify the reliability of the LaTeX-to-MathML
13994 converter, use the following commands:
13996 - {{{kbd(M-x org-export-as-odf)}}} ::
13998 Convert a LaTeX math snippet to an OpenDocument formula (=.odf=)
14001 - {{{kbd(M-x org-export-as-odf-and-open)}}} ::
14003 Convert a LaTeX math snippet to an OpenDocument formula (=.odf=)
14004 file and open the formula file with the system-registered
14011 #+cindex: ImageMagick
14012 Add this line to the Org file. This option is activated on
14015 : #+OPTIONS: tex:dvipng
14017 : #+OPTIONS: tex:dvisvgm
14019 #+texinfo: @noindent
14022 : #+OPTIONS: tex:imagemagick
14024 Under this option, LaTeX fragments are processed into PNG or SVG
14025 images and the resulting images are embedded in the exported
14026 document. This method requires dvipng program, dvisvgm or
14027 ImageMagick programs.
14029 **** MathML and OpenDocument formula files
14031 :DESCRIPTION: Embedding in native format.
14034 When embedding LaTeX math snippets in ODT documents is not reliable,
14035 there is one more option to try. Embed an equation by linking to its
14036 MathML (=.mml=) source or its OpenDocument formula (=.odf=) file as
14039 : [[./equation.mml]]
14041 #+texinfo: @noindent
14044 : [[./equation.odf]]
14046 *** Labels and captions in ODT export
14048 :DESCRIPTION: Rendering objects.
14051 ODT format handles labeling and captioning of objects based on their
14052 types. Inline images, tables, LaTeX fragments, and Math formulas are
14053 numbered and captioned separately. Each object also gets a unique
14054 sequence number based on its order of first appearance in the Org
14055 file. Each category has its own sequence. A caption is just a label
14056 applied to these objects.
14059 ,#+CAPTION: Bell curve
14060 ,#+NAME: fig:SED-HR4049
14064 When rendered, it may show as follows in the exported document:
14066 : Figure 2: Bell curve
14068 #+vindex: org-odt-category-map-alist
14069 To modify the category component of the caption, customize the option
14070 ~org-odt-category-map-alist~. For example, to tag embedded images
14071 with the string "Illustration" instead of the default string "Figure",
14072 use the following setting:
14074 #+begin_src emacs-lisp
14075 (setq org-odt-category-map-alist
14076 '(("__Figure__" "Illustration" "value" "Figure" org-odt--enumerable-image-p)))
14079 With the above modification, the previous example changes to:
14081 : Illustration 2: Bell curve
14083 *** Literal examples in ODT export
14085 :DESCRIPTION: For source code and example blocks.
14088 The ODT export back-end supports literal examples (see [[*Literal
14089 Examples]]) with full fontification. Internally, the ODT export
14090 back-end relies on =htmlfontify.el= to generate the style definitions
14091 needed for fancy listings. The auto-generated styles get =OrgSrc=
14092 prefix and inherit colors from the faces used by Emacs Font Lock
14093 library for that source language.
14095 #+vindex: org-odt-fontify-srcblocks
14096 For custom fontification styles, customize the
14097 ~org-odt-create-custom-styles-for-srcblocks~ option.
14099 #+vindex: org-odt-create-custom-styles-for-srcblocks
14100 To turn off fontification of literal examples, customize the
14101 ~org-odt-fontify-srcblocks~ option.
14103 *** Advanced topics in ODT export
14105 :DESCRIPTION: For power users.
14108 The ODT export back-end has extensive features useful for power users
14109 and frequent uses of ODT formats.
14111 **** Configuring a document converter
14113 :DESCRIPTION: Registering a document converter.
14117 #+cindex: doc, docx, rtf
14118 #+cindex: converter
14120 The ODT export back-end works with popular converters with little or
14121 no extra configuration. See [[*Extending ODT export]]. The following is
14122 for unsupported converters or tweaking existing defaults.
14124 - Register the converter ::
14126 #+vindex: org-export-odt-convert-processes
14127 Add the name of the converter to the ~org-odt-convert-processes~
14128 variable. Note that it also requires how the converter is invoked
14129 on the command line. See the variable's docstring for details.
14131 - Configure its capabilities ::
14133 #+vindex: org-export-odt-convert-capabilities
14134 Specify which formats the converter can handle by customizing the
14135 variable ~org-odt-convert-capabilities~. Use the entry for the
14136 default values in this variable for configuring the new converter.
14137 Also see its docstring for details.
14139 - Choose the converter ::
14141 #+vindex: org-export-odt-convert-process
14142 Select the newly added converter as the preferred one by customizing
14143 the option ~org-odt-convert-process~.
14145 **** Working with OpenDocument style files
14147 :DESCRIPTION: Exploring internals.
14150 #+cindex: styles, custom
14151 #+cindex: template, custom
14153 This section explores the internals of the ODT exporter; the means by which
14154 it produces styled documents; the use of automatic and custom OpenDocument
14157 The ODT exporter relies on two files for generating its output. These
14158 files are bundled with the distribution under the directory pointed to
14159 by the variable ~org-odt-styles-dir~. The two files are:
14161 - =OrgOdtStyles.xml= <<x-orgodtstyles-xml>> ::
14163 This file contributes to the =styles.xml= file of the final ODT
14164 document. This file gets modified for the following purposes:
14166 1. To control outline numbering based on user settings;
14168 2. To add styles generated by =htmlfontify.el= for fontification of
14171 - =OrgOdtContentTemplate.xml= <<x-orgodtcontenttemplate-xml>> ::
14173 This file contributes to the =content.xml= file of the final ODT
14174 document. The contents of the Org outline are inserted between the
14175 =<office:text>= ... =</office:text>= elements of this file.
14177 Apart from serving as a template file for the final =content.xml=,
14178 the file serves the following purposes:
14180 1. It contains automatic styles for formatting of tables which are
14181 referenced by the exporter;
14183 2. It contains =<text:sequence-decl>= ... =</text:sequence-decl>=
14184 elements that control numbering of tables, images, equations, and
14187 <<x-overriding-factory-styles>> The following two variables control
14188 the location from where the ODT exporter picks up the custom styles
14189 and content template files. Customize these variables to override the
14190 factory styles used by the exporter.
14192 - ~org-odt-styles-file~ ::
14194 The ODT export back-end uses the file pointed to by this variable,
14195 such as =styles.xml=, for the final output. It can take one of the
14200 Use this file instead of the default =styles.xml=
14202 - =FILE.odt= or =FILE.ott= ::
14204 Use the =styles.xml= contained in the specified OpenDocument
14205 Text or Template file
14207 - =FILE.odt= or =FILE.ott= and a subset of included files ::
14209 Use the =styles.xml= contained in the specified OpenDocument Text
14210 or Template file. Additionally extract the specified member files
14211 and embed those within the final ODT document.
14213 Use this option if the =styles.xml= file references additional
14214 files like header and footer images.
14218 Use the default =styles.xml=.
14220 - ~org-odt-content-template-file~ ::
14222 Use this variable to specify the blank =content.xml= used in the
14225 **** Creating one-off styles
14227 :DESCRIPTION: Customizing styles, highlighting...
14231 The ODT export back-end can read embedded raw OpenDocument XML from
14232 the Org file. Such direct formatting is useful for one-off instances.
14234 - Embedding ODT tags as part of regular text ::
14236 Enclose OpenDocument syntax in =@@odt:...@@= for inline markup. For
14237 example, to highlight a region of text do the following:
14240 @@odt:<text:span text:style-name="Highlight">This is highlighted
14241 text</text:span>@@. But this is regular text.
14244 *Hint:* To see the above example in action, edit the =styles.xml=
14245 (see [[x-orgodtstyles-xml][Factory styles]]) and add a custom /Highlight/ style as shown
14249 <style:style style:name="Highlight" style:family="text">
14250 <style:text-properties fo:background-color="#ff0000"/>
14254 - Embedding a one-line OpenDocument XML ::
14256 #+cindex: @samp{ODT}, keyword
14257 The ODT export back-end can read one-liner options with =#+ODT:= in
14258 the Org file. For example, to force a page break:
14261 ,#+ODT: <text:p text:style-name="PageBreak"/>
14264 *Hint:* To see the above example in action, edit your
14265 =styles.xml= (see [[x-orgodtstyles-xml][Factory styles]]) and add a custom =PageBreak=
14266 style as shown below.
14269 <style:style style:name="PageBreak" style:family="paragraph"
14270 style:parent-style-name="Text_20_body">
14271 <style:paragraph-properties fo:break-before="page"/>
14275 - Embedding a block of OpenDocument XML ::
14277 The ODT export back-end can also read ODT export blocks for
14278 OpenDocument XML. Such blocks use the =#+BEGIN_EXPORT odt=
14279 ... =#+END_EXPORT= constructs.
14281 For example, to create a one-off paragraph that uses bold text, do
14285 ,#+BEGIN_EXPORT odt
14286 <text:p text:style-name="Text_20_body_20_bold">
14287 This paragraph is specially formatted and uses bold text.
14292 **** Customizing tables in ODT export
14294 :DESCRIPTION: Defining table templates.
14297 #+cindex: tables, in ODT export
14298 #+cindex: @samp{ATTR_ODT}, keyword
14300 Override the default table format by specifying a custom table style
14301 with the =#+ATTR_ODT= line. For a discussion on default formatting of
14302 tables, see [[*Tables in ODT export]].
14304 This feature closely mimics the way table templates are defined in the
14305 OpenDocument-v1.2 specification[fn:136].
14307 #+vindex: org-odt-table-styles
14308 For quick preview of this feature, install the settings below and export the
14309 table that follows:
14311 #+begin_src emacs-lisp
14312 (setq org-export-odt-table-styles
14313 (append org-export-odt-table-styles
14314 '(("TableWithHeaderRowAndColumn" "Custom"
14315 ((use-first-row-styles . t)
14316 (use-first-column-styles . t)))
14317 ("TableWithFirstRowandLastRow" "Custom"
14318 ((use-first-row-styles . t)
14319 (use-last-row-styles . t))))))
14323 ,#+ATTR_ODT: :style TableWithHeaderRowAndColumn
14324 | Name | Phone | Age |
14325 | Peter | 1234 | 17 |
14326 | Anna | 4321 | 25 |
14329 The example above used =Custom= template and installed two table
14330 styles =TableWithHeaderRowAndColumn= and
14331 =TableWithFirstRowandLastRow=. *Important:* The OpenDocument styles
14332 needed for producing the above template were pre-defined. They are
14333 available in the section marked =Custom Table Template= in
14334 =OrgOdtContentTemplate.xml= (see [[x-orgodtcontenttemplate-xml][Factory styles]]). For adding new
14335 templates, define new styles there.
14337 To use this feature proceed as follows:
14339 1. Create a table template[fn:137].
14341 A table template is set of =table-cell= and =paragraph= styles for
14342 each of the following table cell categories:
14354 The names for the above styles must be chosen based on the name of
14355 the table template using a well-defined convention.
14357 The naming convention is better illustrated with an example. For
14358 a table template with the name =Custom=, the needed style names are
14359 listed in the following table.
14361 | Cell type | Cell style | Paragraph style |
14362 |--------------+------------------------------+-----------------------------------|
14363 | Body | =CustomTableCell= | =CustomTableParagraph= |
14364 | First column | =CustomFirstColumnTableCell= | =CustomFirstColumnTableParagraph= |
14365 | Last column | =CustomLastColumnTableCell= | =CustomLastColumnTableParagraph= |
14366 | First row | =CustomFirstRowTableCell= | =CustomFirstRowTableParagraph= |
14367 | Last row | =CustomLastRowTableCell= | =CustomLastRowTableParagraph= |
14368 | Even row | =CustomEvenRowTableCell= | =CustomEvenRowTableParagraph= |
14369 | Odd row | =CustomOddRowTableCell= | =CustomOddRowTableParagraph= |
14370 | Even column | =CustomEvenColumnTableCell= | =CustomEvenColumnTableParagraph= |
14371 | Odd column | =CustomOddColumnTableCell= | =CustomOddColumnTableParagraph= |
14373 To create a table template with the name =Custom=, define the above
14374 styles in the =<office:automatic-styles>= ...
14375 =</office:automatic-styles>= element of the content template file
14376 (see [[x-orgodtcontenttemplate-xml][Factory styles]]).
14378 2. Define a table style[fn:138].
14380 #+vindex: org-odt-table-styles
14381 To define a table style, create an entry for the style in the
14382 variable ~org-odt-table-styles~ and specify the following:
14384 - the name of the table template created in step (1),
14385 - the set of cell styles in that template that are to be activated.
14387 For example, the entry below defines two different table styles
14388 =TableWithHeaderRowAndColumn= and =TableWithFirstRowandLastRow=
14389 based on the same template =Custom=. The styles achieve their
14390 intended effect by selectively activating the individual cell
14391 styles in that template.
14393 #+begin_src emacs-lisp
14394 (setq org-export-odt-table-styles
14395 (append org-export-odt-table-styles
14396 '(("TableWithHeaderRowAndColumn" "Custom"
14397 ((use-first-row-styles . t)
14398 (use-first-column-styles . t)))
14399 ("TableWithFirstRowandLastRow" "Custom"
14400 ((use-first-row-styles . t)
14401 (use-last-row-styles . t))))))
14404 3. Associate a table with the table style.
14406 To do this, specify the table style created in step (2) as part of
14407 the =ATTR_ODT= line as shown below.
14410 ,#+ATTR_ODT: :style TableWithHeaderRowAndColumn
14411 | Name | Phone | Age |
14412 | Peter | 1234 | 17 |
14413 | Anna | 4321 | 25 |
14416 **** Validating OpenDocument XML
14418 :DESCRIPTION: Debugging corrupted OpenDocument files.
14422 Sometimes ODT format files may not open due to =.odt= file corruption.
14423 To verify if such a file is corrupt, validate it against the
14424 OpenDocument Relax NG Compact (RNC) syntax schema. But first the
14425 =.odt= files have to be decompressed using =zip=. Note that =.odt=
14426 files are ZIP archives: [[info:emacs::File Archives]]. The contents of
14427 ODT files are in XML. For general help with validation---and
14428 schema-sensitive editing---of XML files: [[info:nxml-mode::Introduction]].
14430 #+vindex: org-export-odt-schema-dir
14431 Customize ~org-odt-schema-dir~ to point to a directory with
14432 OpenDocument RNC files and the needed schema-locating rules. The ODT
14433 export back-end takes care of updating the
14434 ~rng-schema-locating-files~.
14438 :DESCRIPTION: Exporting to Org.
14441 #+cindex: Org export
14442 /org/ export back-end creates a normalized version of the Org document
14443 in current buffer. The exporter evaluates Babel code (see [[*Evaluating
14444 Code Blocks]]) and removes content specific to other back-ends.
14446 *** Org export commands
14451 - {{{kbd(C-c C-e O o)}}} (~org-org-export-to-org~) ::
14453 #+kindex: C-c C-e O o
14454 #+findex: org-org-export-to-org
14455 Export as an Org file with a =.org= extension. For =myfile.org=,
14456 Org exports to =myfile.org.org=, overwriting without warning.
14458 - {{{kbd(C-c C-e O v)}}} (~~) ::
14460 #+kindex: C-c C-e O v
14461 Export to an Org file, then open it.
14465 :DESCRIPTION: Exporting to Texinfo.
14468 *** Texinfo export commands
14470 :DESCRIPTION: Invoking commands.
14473 - {{{kbd(C-c C-e i t)}}} (~org-texinfo-export-to-texinfo~) ::
14475 #+kindex: C-c C-e i t
14476 #+findex: org-texinfo-export-to-texinfo
14477 Export as a Texinfo file with =.texi= extension. For =myfile.org=,
14478 Org exports to =myfile.texi=, overwriting without warning.
14480 - {{{kbd(C-c C-e i i)}}} (~org-texinfo-export-to-info~) ::
14482 #+kindex: C-c C-e i i
14483 #+findex: org-texinfo-export-to-info
14484 #+vindex: org-texinfo-info-process
14485 Export to Texinfo format first and then process it to make an Info
14486 file. To generate other formats, such as DocBook, customize the
14487 ~org-texinfo-info-process~ variable.
14489 *** Texinfo specific export settings
14491 :DESCRIPTION: Setting the environment.
14494 The Texinfo export back-end has several additional keywords for
14495 customizing Texinfo output. Setting these keywords works similar to
14496 the general options (see [[*Export Settings]]).
14500 #+cindex: @samp{SUBTITLE}, keyword
14501 The document subtitle.
14505 #+cindex: @samp{SUBAUTHOR}, keyword
14506 Additional authors for the document.
14508 - =TEXINFO_FILENAME= ::
14510 #+cindex: @samp{TEXINFO_FILENAME}, keyword
14511 The Texinfo filename.
14513 - =TEXINFO_CLASS= ::
14515 #+cindex: @samp{TEXINFO_CLASS}, keyword
14516 #+vindex: org-texinfo-default-class
14517 The default document class (~org-texinfo-default-class~), which must
14518 be a member of ~org-texinfo-classes~.
14520 - =TEXINFO_HEADER= ::
14522 #+cindex: @samp{TEXINFO_HEADER}, keyword
14523 Arbitrary lines inserted at the end of the header.
14525 - =TEXINFO_POST_HEADER= ::
14527 #+cindex: @samp{TEXINFO_POST_HEADER}, keyword
14528 Arbitrary lines inserted after the end of the header.
14530 - =TEXINFO_DIR_CATEGORY= ::
14532 #+cindex: @samp{TEXINFO_DIR_CATEGORY}, keyword
14533 The directory category of the document.
14535 - =TEXINFO_DIR_TITLE= ::
14537 #+cindex: @samp{TEXINFO_DIR_TITLE}, keyword
14538 The directory title of the document.
14540 - =TEXINFO_DIR_DESC= ::
14542 #+cindex: @samp{TEXINFO_DIR_DESC}, keyword
14543 The directory description of the document.
14545 - =TEXINFO_PRINTED_TITLE= ::
14547 #+cindex: @samp{TEXINFO_PRINTED_TITLE}, keyword
14548 The printed title of the document.
14550 *** Texinfo file header
14552 :DESCRIPTION: Generating the header.
14555 #+cindex: @samp{TEXINFO_FILENAME}, keyword
14556 After creating the header for a Texinfo file, the Texinfo back-end
14557 automatically generates a name and destination path for the Info file.
14558 To override this default with a more sensible path and name, specify
14559 the =TEXINFO_FILENAME= keyword.
14561 #+vindex: org-texinfo-coding-system
14562 #+cindex: @samp{TEXINFO_HEADER}, keyword
14563 Along with the output's file name, the Texinfo header also contains
14564 language details (see [[*Export Settings]]) and encoding system as set in
14565 the ~org-texinfo-coding-system~ variable. Insert =TEXINFO_HEADER=
14566 keywords for each additional command in the header, for example:
14568 : #+TEXINFO_HEADER: @synindex
14570 #+cindex: @samp{TEXINFO_CLASS}, keyword
14571 #+vindex: org-texinfo-classes
14572 Instead of repeatedly installing the same set of commands, define
14573 a class in ~org-texinfo-classes~ once, and then activate it in the
14574 document by setting the =TEXINFO_CLASS= keyword to that class.
14576 *** Texinfo title and copyright page
14578 :DESCRIPTION: Creating preamble pages.
14581 #+cindex: @samp{TEXINFO_PRINTED_TITLE}, keyword
14582 The default template for hard copy output has a title page with
14583 =TITLE= and =AUTHOR= keywords (see [[*Export Settings]]). To replace the
14584 regular title with something different for the printed version, use
14585 the =TEXINFO_PRINTED_TITLE= and =SUBTITLE= keywords. Both expect raw
14586 Texinfo code for setting their values.
14588 #+cindex: @samp{SUBAUTHOR}, keyword
14589 If one =AUTHOR= line is not sufficient, add multiple =SUBAUTHOR=
14590 keywords. They have to be set in raw Texinfo code.
14593 ,#+AUTHOR: Jane Smith
14594 ,#+SUBAUTHOR: John Doe
14595 ,#+TEXINFO_PRINTED_TITLE: This Long Title@@inlinefmt{tex,@*} Is Broken in @TeX{}
14598 #+cindex: @samp{COPYING}, property
14599 Copying material is defined in a dedicated headline with a non-~nil~
14600 =COPYING= property. The back-end inserts the contents within
14601 a =@copying= command at the beginning of the document. The heading
14602 itself does not appear in the structure of the document.
14604 Copyright information is printed on the back of the title page.
14612 This is a short example of a complete Texinfo file, version 1.0.
14614 Copyright \copy 2016 Free Software Foundation, Inc.
14617 *** Info directory file
14619 :DESCRIPTION: Installing a manual in Info file hierarchy.
14622 #+cindex: @samp{dir} file, in Texinfo export
14623 #+cindex: Info directory file, in Texinfo export
14624 #+cindex: @code{install-info}, in Texinfo export
14626 #+cindex: @samp{TEXINFO_DIR_CATEGORY}, keyword
14627 #+cindex: @samp{TEXINFO_DIR_TITLE}, keyword
14628 #+cindex: @samp{TEXINFO_DIR_DESC}, keyword
14629 The end result of the Texinfo export process is the creation of an
14630 Info file. This Info file's metadata has variables for category,
14631 title, and description: =TEXINFO_DIR_CATEGORY=, =TEXINFO_DIR_TITLE=,
14632 and =TEXINFO_DIR_DESC= keywords that establish where in the Info
14633 hierarchy the file fits.
14635 Here is an example that writes to the Info directory file:
14638 ,#+TEXINFO_DIR_CATEGORY: Emacs
14639 ,#+TEXINFO_DIR_TITLE: Org Mode: (org)
14640 ,#+TEXINFO_DIR_DESC: Outline-based notes management and organizer
14643 *** Headings and sectioning structure
14645 :DESCRIPTION: Building document structure.
14648 #+vindex: org-texinfo-classes
14649 #+vindex: org-texinfo-default-class
14650 #+cindex: @samp{TEXINFO_CLASS}, keyword
14651 The Texinfo export back-end uses a pre-defined scheme to convert Org
14652 headlines to equivalent Texinfo structuring commands. A scheme like
14653 this maps top-level headlines to numbered chapters tagged as
14654 ~@chapter~ and lower-level headlines to unnumbered chapters tagged as
14655 ~@unnumbered~. To override such mappings to introduce ~@part~ or
14656 other Texinfo structuring commands, define a new class in
14657 ~org-texinfo-classes~. Activate the new class with the
14658 =TEXINFO_CLASS= keyword. When no new class is defined and activated,
14659 the Texinfo export back-end defaults to the
14660 ~org-texinfo-default-class~.
14662 If an Org headline's level has no associated Texinfo structuring
14663 command, or is below a certain threshold (see [[*Export Settings]]), then
14664 the Texinfo export back-end makes it into a list item.
14666 #+cindex: @samp{APPENDIX}, property
14667 The Texinfo export back-end makes any headline with a non-~nil~
14668 =APPENDIX= property into an appendix. This happens independent of the
14669 Org headline level or the =TEXINFO_CLASS= keyword.
14671 #+cindex: @samp{ALT_TITLE}, property
14672 #+cindex: @samp{DESCRIPTION}, property
14673 The Texinfo export back-end creates a menu entry after the Org
14674 headline for each regular sectioning structure. To override this with
14675 a shorter menu entry, use the =ALT_TITLE= property (see [[*Table of
14676 Contents]]). Texinfo menu entries also have an option for a longer
14677 =DESCRIPTION= property. Here's an example that uses both to override
14678 the default menu entry:
14681 ,* Controlling Screen Display
14683 :ALT_TITLE: Display
14684 :DESCRIPTION: Controlling Screen Display
14688 #+cindex: Top node, in Texinfo export
14689 The text before the first headline belongs to the /Top/ node, i.e.,
14690 the node in which a reader enters an Info manual. As such, it is
14691 expected not to appear in printed output generated from the =.texi=
14692 file. See [[info:texinfo::The%20Top%20Node]], for more information.
14696 :DESCRIPTION: Creating indices.
14699 #+cindex: @samp{CINDEX}, keyword
14700 #+cindex: concept index, in Texinfo export
14701 #+cindex: @samp{FINDEX}, keyword
14702 #+cindex: function index, in Texinfo export
14703 #+cindex: @samp{KINDEX}, keyword
14704 #+cindex: keystroke index, in Texinfo export
14705 #+cindex: @samp{PINDEX}, keyword
14706 #+cindex: program index, in Texinfo export
14707 #+cindex: @samp{TINDEX}, keyword
14708 #+cindex: data type index, in Texinfo export
14709 #+cindex: @samp{VINDEX}, keyword
14710 #+cindex: variable index, in Texinfo export
14711 The Texinfo export back-end recognizes these indexing keywords if used
14712 in the Org file: =CINDEX=, =FINDEX=, =KINDEX=, =PINDEX=, =TINDEX= and
14713 =VINDEX=. Write their value as verbatim Texinfo code; in particular,
14714 ={=, =}= and =@= characters need to be escaped with =@= if they do not
14715 belong to a Texinfo command.
14717 : #+CINDEX: Defining indexing entries
14719 #+cindex: @samp{INDEX}, property
14720 For the back-end to generate an index entry for a headline, set the
14721 =INDEX= property to =cp= or =vr=. These abbreviations come from
14722 Texinfo that stand for concept index and variable index. The Texinfo
14723 manual has abbreviations for all other kinds of indexes. The back-end
14724 exports the headline as an unnumbered chapter or section command, and
14725 then inserts the index after its contents.
14734 *** Quoting Texinfo code
14736 :DESCRIPTION: Incorporating literal Texinfo code.
14739 Use any of the following three methods to insert or escape raw Texinfo
14742 #+cindex: @samp{TEXINFO}, keyword
14743 #+cindex: @samp{BEGIN_EXPORT texinfo}
14745 Richard @@texinfo:@sc{@@Stallman@@texinfo:}@@ commence' GNU.
14747 ,#+TEXINFO: @need800
14748 This paragraph is preceded by...
14750 ,#+BEGIN_EXPORT texinfo
14751 @auindex Johnson, Mark
14752 @auindex Lakoff, George
14756 *** Plain lists in Texinfo export
14758 :DESCRIPTION: List attributes.
14761 #+cindex: @samp{ATTR_TEXINFO}, keyword
14762 #+cindex: two-column tables, in Texinfo export
14764 #+cindex: table types, in Texinfo export
14765 The Texinfo export back-end by default converts description lists in
14766 the Org file using the default command =@table=, which results in
14767 a table with two columns. To change this behavior, specify
14768 =:table-type= with =ftable= or =vtable= attributes. For more
14769 information, see [[info:texinfo::Two-column Tables]].
14771 #+vindex: org-texinfo-table-default-markup
14772 The Texinfo export back-end by default also applies a text highlight
14773 based on the defaults stored in ~org-texinfo-table-default-markup~.
14774 To override the default highlight command, specify another one with
14775 the =:indic= attribute.
14777 #+cindex: multiple items in Texinfo lists
14778 Org syntax is limited to one entry per list item. Nevertheless, the
14779 Texinfo export back-end can split that entry according to any text
14780 provided through the =:sep= attribute. Each part then becomes a new
14781 entry in the first column of the table.
14783 The following example illustrates all the attributes above:
14786 ,#+ATTR_TEXINFO: :table-type vtable :sep , :indic asis
14787 - foo, bar :: This is the common text for variables foo and bar.
14790 #+texinfo: @noindent
14797 This is the common text for variables foo and bar.
14801 *** Tables in Texinfo export
14803 :DESCRIPTION: Table attributes.
14806 #+cindex: @samp{ATTR_TEXINFO}, keyword
14807 When exporting tables, the Texinfo export back-end uses the widest
14808 cell width in each column. To override this and instead specify as
14809 fractions of line length, use the =:columns= attribute. See example
14813 ,#+ATTR_TEXINFO: :columns .5 .5
14814 | a cell | another cell |
14817 *** Images in Texinfo export
14819 :DESCRIPTION: Image attributes.
14822 #+cindex: @samp{ATTR_TEXINFO}, keyword
14823 Insert a file link to the image in the Org file, and the Texinfo
14824 export back-end inserts the image. These links must have the usual
14825 supported image extensions and no descriptions. To scale the image,
14826 use =:width= and =:height= attributes. For alternate text, use =:alt=
14827 and specify the text using Texinfo code, as shown in the example:
14830 ,#+ATTR_TEXINFO: :width 1in :alt Alternate @i{text}
14834 *** Quotations in Texinfo export
14836 :DESCRIPTION: Quote block attributes.
14839 #+cindex: @samp{ATTR_TEXINFO}, keyword
14840 You can write the text of a quotation within a quote block (see
14841 [[*Paragraphs]]). You may also emphasize some text at the beginning of
14842 the quotation with the =:tag= attribute.
14845 ,#+ATTR_TEXINFO: :tag Warning
14847 Striking your thumb with a hammer may cause severe pain and discomfort.
14851 To specify the author of the quotation, use the =:author= attribute.
14854 ,#+ATTR_TEXINFO: :author King Arthur
14856 The Lady of the Lake, her arm clad in the purest shimmering samite,
14857 held aloft Excalibur from the bosom of the water, signifying by divine
14858 providence that I, Arthur, was to carry Excalibur. That is why I am
14863 *** Special blocks in Texinfo export
14865 :DESCRIPTION: Special block attributes.
14868 #+cindex: @samp{ATTR_TEXINFO}, keyword
14870 The Texinfo export back-end converts special blocks to commands with
14871 the same name. It also adds any =:options= attributes to the end of
14872 the command, as shown in this example:
14875 ,#+ATTR_TEXINFO: :options org-org-export-to-org ...
14877 A somewhat obsessive function name.
14881 #+texinfo: @noindent
14885 @defun org-org-export-to-org ...
14886 A somewhat obsessive function name.
14890 *** A Texinfo example
14892 :DESCRIPTION: Processing Org to Texinfo.
14895 Here is a more detailed example Org file. See
14896 [[info:texinfo::GNU%20Sample%20Texts]] for an equivalent example using
14900 ,#+TITLE: GNU Sample {{{version}}}
14901 ,#+SUBTITLE: for version {{{version}}}, {{{updated}}}
14902 ,#+AUTHOR: A.U. Thor
14903 ,#+EMAIL: bug-sample@gnu.org
14905 ,#+OPTIONS: ':t toc:t author:t email:t
14908 ,#+MACRO: version 2.0
14909 ,#+MACRO: updated last updated 4 March 2014
14911 ,#+TEXINFO_FILENAME: sample.info
14912 ,#+TEXINFO_HEADER: @syncodeindex pg cp
14914 ,#+TEXINFO_DIR_CATEGORY: Texinfo documentation system
14915 ,#+TEXINFO_DIR_TITLE: sample: (sample)
14916 ,#+TEXINFO_DIR_DESC: Invoking sample
14918 ,#+TEXINFO_PRINTED_TITLE: GNU Sample
14920 This manual is for GNU Sample (version {{{version}}},
14928 This manual is for GNU Sample (version {{{version}}},
14929 {{{updated}}}), which is an example in the Texinfo documentation.
14931 Copyright \copy 2016 Free Software Foundation, Inc.
14934 Permission is granted to copy, distribute and/or modify this
14935 document under the terms of the GNU Free Documentation License,
14936 Version 1.3 or any later version published by the Free Software
14937 Foundation; with no Invariant Sections, with no Front-Cover Texts,
14938 and with no Back-Cover Texts. A copy of the license is included in
14939 the section entitled "GNU Free Documentation License".
14945 ,#+CINDEX: invoking @command{sample}
14947 This is a sample manual. There is no sample program to invoke, but
14948 if there were, you could see its basic usage and command line
14951 ,* GNU Free Documentation License
14956 ,#+TEXINFO: @include fdl.texi
14964 ** iCalendar Export
14966 :DESCRIPTION: Exporting to iCalendar.
14968 #+cindex: iCalendar export
14970 A large part of Org mode's interoperability success is its ability to
14971 easily export to or import from external applications. The iCalendar
14972 export back-end takes calendar data from Org files and exports to the
14973 standard iCalendar format.
14975 #+vindex: org-icalendar-include-todo
14976 #+vindex: org-icalendar-use-deadline
14977 #+vindex: org-icalendar-use-scheduled
14978 The iCalendar export back-end can also incorporate TODO entries based
14979 on the configuration of the ~org-icalendar-include-todo~ variable.
14980 The back-end exports plain timestamps as =VEVENT=, TODO items as
14981 =VTODO=, and also create events from deadlines that are in non-TODO
14982 items. The back-end uses the deadlines and scheduling dates in Org
14983 TODO items for setting the start and due dates for the iCalendar TODO
14984 entry. Consult the ~org-icalendar-use-deadline~ and
14985 ~org-icalendar-use-scheduled~ variables for more details.
14987 #+vindex: org-icalendar-categories
14988 #+vindex: org-icalendar-alarm-time
14989 For tags on the headline, the iCalendar export back-end makes them
14990 into iCalendar categories. To tweak the inheritance of tags and TODO
14991 states, configure the variable ~org-icalendar-categories~. To assign
14992 clock alarms based on time, configure the ~org-icalendar-alarm-time~
14995 #+vindex: org-icalendar-store-UID
14996 #+cindex: @samp{ID}, property
14997 The iCalendar format standard requires globally unique identifier---or
14998 UID---for each entry. The iCalendar export back-end creates UIDs
14999 during export. To save a copy of the UID in the Org file set the
15000 variable ~org-icalendar-store-UID~. The back-end looks for the =ID=
15001 property of the entry for re-using the same UID for subsequent
15004 Since a single Org entry can result in multiple iCalendar
15005 entries---timestamp, deadline, scheduled item, or TODO item---Org adds
15006 prefixes to the UID, depending on which part of the Org entry
15007 triggered the creation of the iCalendar entry. Prefixing ensures UIDs
15008 remains unique, yet enable synchronization programs trace the
15011 - {{{kbd(C-c C-e c f)}}} (~org-icalendar-export-to-ics~) ::
15013 #+kindex: C-c C-e c f
15014 #+findex: org-icalendar-export-to-ics
15015 Create iCalendar entries from the current Org buffer and store them
15016 in the same directory, using a file extension =.ics=.
15018 - {{{kbd(C-c C-e c a)}}} (~org-icalendar-export-agenda-files~) ::
15020 #+kindex: C-c C-e c a
15021 #+findex: org-icalendar-export-agenda-files
15022 Create iCalendar entries from Org files in ~org-agenda-files~ and
15023 store in a separate iCalendar file for each Org file.
15025 - {{{kbd(C-c C-e c c)}}} (~org-icalendar-combine-agenda-files~) ::
15027 #+kindex: C-c C-e c c
15028 #+findex: org-icalendar-combine-agenda-files
15029 #+vindex: org-icalendar-combined-agenda-file
15030 Create a combined iCalendar file from Org files in
15031 ~org-agenda-files~ and write it to
15032 ~org-icalendar-combined-agenda-file~ file name.
15034 #+cindex: @samp{SUMMARY}, property
15035 #+cindex: @samp{DESCRIPTION}, property
15036 #+cindex: @samp{LOCATION}, property
15037 #+cindex: @samp{TIMEZONE}, property
15038 #+cindex: @samp{CLASS}, property
15039 The iCalendar export back-end includes =SUMMARY=, =DESCRIPTION=,
15040 =LOCATION=, =TIMEZONE= and =CLASS= properties from the Org entries
15041 when exporting. To force the back-end to inherit the =LOCATION=,
15042 =TIMEZONE= and =CLASS= properties, configure the
15043 ~org-use-property-inheritance~ variable.
15045 #+vindex: org-icalendar-include-body
15046 When Org entries do not have =SUMMARY=, =DESCRIPTION=, =LOCATION= and
15047 =CLASS= properties, the iCalendar export back-end derives the summary
15048 from the headline, and derives the description from the body of the
15049 Org item. The ~org-icalendar-include-body~ variable limits the
15050 maximum number of characters of the content are turned into its
15053 The =TIMEZONE= property can be used to specify a per-entry time zone,
15054 and is applied to any entry with timestamp information. Time zones
15055 should be specified as per the IANA time zone database format, e.g.,
15056 =Asia/Almaty=. Alternately, the property value can be =UTC=, to force
15057 UTC time for this entry only.
15059 The =CLASS= property can be used to specify a per-entry visibility
15060 class or access restrictions, and is applied to any entry with class
15061 information. The iCalendar standard defines three visibility classes:
15062 - =PUBLIC= :: The entry is publicly visible (this is the default).
15063 - =CONFIDENTIAL= :: Only a limited group of clients get access to the
15065 - =PRIVATE= :: The entry can be retrieved only by its owner.
15066 The server should treat unknown class properties the same as
15069 Exporting to iCalendar format depends in large part on the
15070 capabilities of the destination application. Some are more lenient
15071 than others. Consult the Org mode FAQ for advice on specific
15074 ** Other Built-in Back-ends
15076 :DESCRIPTION: Exporting to a man page.
15079 Other export back-ends included with Org are:
15081 - =ox-man.el=: Export to a man page.
15083 To activate such back-ends, either customize ~org-export-backends~ or
15084 load directly with =(require 'ox-man)=. On successful load, the
15085 back-end adds new keys in the export dispatcher (see [[*The Export
15088 Follow the comment section of such files, for example, =ox-man.el=,
15089 for usage and configuration details.
15091 ** Advanced Export Configuration
15093 :DESCRIPTION: Fine-tuning the export output.
15101 #+vindex: org-export-before-processing-hook
15102 #+vindex: org-export-before-parsing-hook
15103 The export process executes two hooks before the actual exporting
15104 begins. The first hook, ~org-export-before-processing-hook~, runs
15105 before any expansions of macros, Babel code, and include keywords in
15106 the buffer. The second hook, ~org-export-before-parsing-hook~, runs
15107 before the buffer is parsed.
15109 Functions added to these hooks are called with a single argument: the
15110 export back-end actually used, as a symbol. You may use them for
15111 heavy duty structural modifications of the document. For example, you
15112 can remove every headline in the buffer during export like this:
15114 #+begin_src emacs-lisp
15115 (defun my-headline-removal (backend)
15116 "Remove all headlines in the current buffer.
15117 BACKEND is the export back-end being used, as a symbol."
15119 (lambda () (delete-region (point) (line-beginning-position 2)))))
15121 (add-hook 'org-export-before-parsing-hook 'my-headline-removal)
15129 #+cindex: Filters, exporting
15130 Filters are lists of functions to be applied to certain parts for
15131 a given back-end. The output from the first function in the filter is
15132 passed on to the next function in the filter. The final output is the
15133 output from the final function in the filter.
15135 The Org export process has many filter sets applicable to different
15136 types of objects, plain text, parse trees, export options, and final
15137 output formats. The filters are named after the element type or
15138 object type: ~org-export-filter-TYPE-functions~, where {{{var(TYPE)}}}
15139 is the type targeted by the filter. Valid types are:
15141 #+attr_texinfo: :columns 0.33 0.33 0.33
15142 | body | bold | babel-call |
15143 | center-block | clock | code |
15144 | diary-sexp | drawer | dynamic-block |
15145 | entity | example-block | export-block |
15146 | export-snippet | final-output | fixed-width |
15147 | footnote-definition | footnote-reference | headline |
15148 | horizontal-rule | inline-babel-call | inline-src-block |
15149 | inlinetask | italic | item |
15150 | keyword | latex-environment | latex-fragment |
15151 | line-break | link | node-property |
15152 | options | paragraph | parse-tree |
15153 | plain-list | plain-text | planning |
15154 | property-drawer | quote-block | radio-target |
15155 | section | special-block | src-block |
15156 | statistics-cookie | strike-through | subscript |
15157 | superscript | table | table-cell |
15158 | table-row | target | timestamp |
15159 | underline | verbatim | verse-block |
15161 Here is an example filter that replaces non-breaking spaces ~Â ~ in the
15162 Org buffer with =~= for the LaTeX back-end.
15164 #+begin_src emacs-lisp
15165 (defun my-latex-filter-nobreaks (text backend info)
15166 "Ensure \"Â \" are properly handled in LaTeX export."
15167 (when (org-export-derived-backend-p backend 'latex)
15168 (replace-regexp-in-string "Â " "~" text)))
15170 (add-to-list 'org-export-filter-plain-text-functions
15171 'my-latex-filter-nobreaks)
15174 A filter requires three arguments: the code to be transformed, the
15175 name of the back-end, and some optional information about the export
15176 process. The third argument can be safely ignored. Note the use of
15177 ~org-export-derived-backend-p~ predicate that tests for /latex/
15178 back-end or any other back-end, such as /beamer/, derived from
15181 *** Defining filters for individual files
15186 The Org export can filter not just for back-ends, but also for
15187 specific files through the =BIND= keyword. Here is an example with
15188 two filters; one removes brackets from time stamps, and the other
15189 removes strike-through text. The filter functions are defined in
15190 a code block in the same Org file, which is a handy location for
15194 ,#+BIND: org-export-filter-timestamp-functions (tmp-f-timestamp)
15195 ,#+BIND: org-export-filter-strike-through-functions (tmp-f-strike-through)
15196 ,#+BEGIN_SRC emacs-lisp :exports results :results none
15197 (defun tmp-f-timestamp (s backend info)
15198 (replace-regexp-in-string "&[lg]t;\\|[][]" "" s))
15199 (defun tmp-f-strike-through (s backend info) "")
15203 *** Extending an existing back-end
15208 Some parts of the conversion process can be extended for certain
15209 elements so as to introduce a new or revised translation. That is how
15210 the HTML export back-end was extended to handle Markdown format. The
15211 extensions work seamlessly so any aspect of filtering not done by the
15212 extended back-end is handled by the original back-end. Of all the
15213 export customization in Org, extending is very powerful as it operates
15214 at the parser level.
15216 For this example, make the /ascii/ back-end display the language used
15217 in a source code block. Also make it display only when some attribute
15218 is non-~nil~, like the following:
15220 : #+ATTR_ASCII: :language t
15222 Then extend ASCII back-end with a custom "my-ascii" back-end.
15224 #+begin_src emacs-lisp
15225 (defun my-ascii-src-block (src-block contents info)
15226 "Transcode a SRC-BLOCK element from Org to ASCII.
15227 CONTENTS is nil. INFO is a plist used as a communication
15229 (if (not (org-export-read-attribute :attr_ascii src-block :language))
15230 (org-export-with-backend 'ascii src-block contents info)
15232 (format ",--[ %s ]--\n%s`----"
15233 (org-element-property :language src-block)
15234 (replace-regexp-in-string
15236 (org-element-normalize-string
15237 (org-export-format-code-default src-block info)))))))
15239 (org-export-define-derived-backend 'my-ascii 'ascii
15240 :translate-alist '((src-block . my-ascii-src-block)))
15243 The ~my-ascii-src-block~ function looks at the attribute above the
15244 current element. If not true, hands over to /ascii/ back-end. If
15245 true, which it is in this example, it creates a box around the code
15246 and leaves room for the inserting a string for language. The last
15247 form creates the new back-end that springs to action only when
15248 translating ~src-block~ type elements.
15250 To use the newly defined back-end, evaluate the following from an Org
15253 #+begin_src emacs-lisp
15254 (org-export-to-buffer 'my-ascii "*Org MY-ASCII Export*")
15257 Further steps to consider would be an interactive function,
15258 self-installing an item in the export dispatcher menu, and other
15259 user-friendly improvements.
15261 ** Export in Foreign Buffers
15263 :DESCRIPTION: Author tables and lists in Org syntax.
15266 The export back-ends in Org often include commands to convert selected
15267 regions. A convenient feature of this in-place conversion is that the
15268 exported output replaces the original source. Here are such
15271 - ~org-ascii-convert-region-to-ascii~ ::
15273 #+findex: org-ascii-convert-region-to-ascii
15274 Convert the selected region into ASCII.
15276 - ~org-ascii-convert-region-to-utf8~ ::
15278 #+findex: org-ascii-convert-region-to-utf8
15279 Convert the selected region into UTF-8.
15281 - ~org-html-convert-region-to-html~ ::
15283 #+findex: org-html-convert-region-to-html
15284 Convert the selected region into HTML.
15286 - ~org-latex-convert-region-to-latex~ ::
15288 #+findex: org-latex-convert-region-to-latex
15289 Convert the selected region into LaTeX.
15291 - ~org-texinfo-convert-region-to-texinfo~ ::
15293 #+findex: org-texinfo-convert-region-to-texinfo
15294 Convert the selected region into Texinfo.
15296 - ~org-md-convert-region-to-md~ ::
15298 #+findex: org-md-convert-region-to-md
15299 Convert the selected region into Markdown.
15301 In-place conversions are particularly handy for quick conversion of
15302 tables and lists in foreign buffers. For example, in an HTML buffer,
15303 write a list in Org syntax, select it, and convert it to HTML with
15304 {{{kbd(M-x org-html-convert-region-to-html)}}}.
15308 :DESCRIPTION: Create a web site of linked Org files.
15310 #+cindex: publishing
15312 Org includes a publishing management system that allows you to
15313 configure automatic HTML conversion of /projects/ composed of
15314 interlinked Org files. You can also configure Org to automatically
15315 upload your exported HTML pages and related attachments, such as
15316 images and source code files, to a web server.
15318 You can also use Org to convert files into PDF, or even combine HTML
15319 and PDF conversion so that files are available in both formats on the
15322 Publishing has been contributed to Org by David O'Toole.
15326 :DESCRIPTION: Defining projects.
15328 Publishing needs significant configuration to specify files,
15329 destination and many other properties of a project.
15331 *** The variable ~org-publish-project-alist~
15333 :DESCRIPTION: The central configuration variable.
15334 :ALT_TITLE: Project alist
15336 #+cindex: projects, for publishing
15338 #+vindex: org-publish-project-alist
15339 Publishing is configured almost entirely through setting the value of
15340 one variable, called ~org-publish-project-alist~. Each element of the
15341 list configures one project, and may be in one of the two following
15344 #+begin_src emacs-lisp
15345 ("project-name" :property value :property value ...)
15348 #+texinfo: @noindent
15349 i.e., a well-formed property list with alternating keys and values,
15352 #+begin_src emacs-lisp
15353 ("project-name" :components ("project-name" "project-name" ...))
15356 In both cases, projects are configured by specifying property values.
15357 A project defines the set of files that are to be published, as well
15358 as the publishing configuration to use when publishing those files.
15359 When a project takes the second form listed above, the individual
15360 members of the ~:components~ property are taken to be sub-projects,
15361 which group together files requiring different publishing options.
15362 When you publish such a "meta-project", all the components are also
15363 published, in the sequence given.
15365 *** Sources and destinations for files
15367 :DESCRIPTION: From here to there.
15368 :ALT_TITLE: Sources and destinations
15370 #+cindex: directories, for publishing
15372 Most properties are optional, but some should always be set. In
15373 particular, Org needs to know where to look for source files, and
15374 where to put published files.
15376 - ~:base-directory~ ::
15378 Directory containing publishing source files.
15380 - ~:publishing-directory~ ::
15382 Directory where output files are published. You can directly
15383 publish to a webserver using a file name syntax appropriate for the
15384 Emacs tramp package. Or you can publish to a local directory and
15385 use external tools to upload your website (see [[*Uploading Files]]).
15387 - ~:preparation-function~ ::
15389 Function or list of functions to be called before starting the
15390 publishing process, for example, to run =make= for updating files to
15391 be published. Each preparation function is called with a single
15392 argument, the project property list.
15394 - ~:completion-function~ ::
15396 Function or list of functions called after finishing the publishing
15397 process, for example, to change permissions of the resulting files.
15398 Each completion function is called with a single argument, the
15399 project property list.
15401 *** Selecting files
15403 :DESCRIPTION: What files are part of the project?
15405 #+cindex: files, selecting for publishing
15407 By default, all files with extension =.org= in the base directory are
15408 considered part of the project. This can be modified by setting the
15409 following properties
15411 - ~:base-extension~ ::
15413 Extension---without the dot---of source files. This actually is
15414 a regular expression. Set this to the symbol ~any~ if you want to
15415 get all files in ~:base-directory~, even without extension.
15419 Regular expression to match file names that should not be published,
15420 even though they have been selected on the basis of their extension.
15424 List of files to be included regardless of ~:base-extension~ and
15429 Non-~nil~ means, check base-directory recursively for files to
15432 *** Publishing action
15434 :DESCRIPTION: Setting the function doing the publishing.
15436 #+cindex: action, for publishing
15438 Publishing means that a file is copied to the destination directory
15439 and possibly transformed in the process. The default transformation
15440 is to export Org files as HTML files, and this is done by the function
15441 ~org-publish-org-to-html~ which calls the HTML exporter (see [[*HTML
15442 Export]]). But you can also publish your content as PDF files using
15443 ~org-publish-org-to-pdf~, or as ASCII, Texinfo, etc., using the
15444 corresponding functions.
15446 If you want to publish the Org file as an =.org= file but with
15447 /archived/, /commented/, and /tag-excluded/ trees removed, use
15448 ~org-publish-org-to-org~. This produces =file.org= and put it in the
15449 publishing directory. If you want a htmlized version of this file,
15450 set the parameter ~:htmlized-source~ to ~t~. It produces
15451 =file.org.html= in the publishing directory[fn:139].
15453 Other files like images only need to be copied to the publishing
15454 destination; for this you can use ~org-publish-attachment~. For
15455 non-Org files, you always need to specify the publishing function:
15457 - ~:publishing-function~ ::
15459 Function executing the publication of a file. This may also be
15460 a list of functions, which are all called in turn.
15462 - ~:htmlized-source~ ::
15464 Non-~nil~ means, publish htmlized source.
15466 The function must accept three arguments: a property list containing
15467 at least a ~:publishing-directory~ property, the name of the file to
15468 be published, and the path to the publishing directory of the output
15469 file. It should take the specified file, make the necessary
15470 transformation, if any, and place the result into the destination
15473 *** Options for the exporters
15475 :DESCRIPTION: Tweaking HTML/@LaTeX{} export.
15476 :ALT_TITLE: Publishing options
15478 #+cindex: options, for publishing
15479 #+cindex: publishing options
15481 The property list can be used to set many export options for the HTML
15482 and LaTeX exporters. In most cases, these properties correspond to
15483 user variables in Org. The table below lists these properties along
15484 with the variable they belong to. See the documentation string for
15485 the respective variable for details.
15487 #+vindex: org-publish-project-alist
15488 When a property is given a value in ~org-publish-project-alist~, its
15489 setting overrides the value of the corresponding user variable, if
15490 any, during publishing. Options set within a file (see [[*Export
15491 Settings]]), however, override everything.
15493 **** Generic properties
15498 | ~:archived-trees~ | ~org-export-with-archived-trees~ |
15499 | ~:exclude-tags~ | ~org-export-exclude-tags~ |
15500 | ~:headline-levels~ | ~org-export-headline-levels~ |
15501 | ~:language~ | ~org-export-default-language~ |
15502 | ~:preserve-breaks~ | ~org-export-preserve-breaks~ |
15503 | ~:section-numbers~ | ~org-export-with-section-numbers~ |
15504 | ~:select-tags~ | ~org-export-select-tags~ |
15505 | ~:with-author~ | ~org-export-with-author~ |
15506 | ~:with-broken-links~ | ~org-export-with-broken-links~ |
15507 | ~:with-clocks~ | ~org-export-with-clocks~ |
15508 | ~:with-creator~ | ~org-export-with-creator~ |
15509 | ~:with-date~ | ~org-export-with-date~ |
15510 | ~:with-drawers~ | ~org-export-with-drawers~ |
15511 | ~:with-email~ | ~org-export-with-email~ |
15512 | ~:with-emphasize~ | ~org-export-with-emphasize~ |
15513 | ~:with-fixed-width~ | ~org-export-with-fixed-width~ |
15514 | ~:with-footnotes~ | ~org-export-with-footnotes~ |
15515 | ~:with-latex~ | ~org-export-with-latex~ |
15516 | ~:with-planning~ | ~org-export-with-planning~ |
15517 | ~:with-priority~ | ~org-export-with-priority~ |
15518 | ~:with-properties~ | ~org-export-with-properties~ |
15519 | ~:with-special-strings~ | ~org-export-with-special-strings~ |
15520 | ~:with-sub-superscript~ | ~org-export-with-sub-superscripts~ |
15521 | ~:with-tables~ | ~org-export-with-tables~ |
15522 | ~:with-tags~ | ~org-export-with-tags~ |
15523 | ~:with-tasks~ | ~org-export-with-tasks~ |
15524 | ~:with-timestamps~ | ~org-export-with-timestamps~ |
15525 | ~:with-title~ | ~org-export-with-title~ |
15526 | ~:with-toc~ | ~org-export-with-toc~ |
15527 | ~:with-todo-keywords~ | ~org-export-with-todo-keywords~ |
15529 **** ASCII specific properties
15534 | ~:ascii-bullets~ | ~org-ascii-bullets~ |
15535 | ~:ascii-caption-above~ | ~org-ascii-caption-above~ |
15536 | ~:ascii-charset~ | ~org-ascii-charset~ |
15537 | ~:ascii-global-margin~ | ~org-ascii-global-margin~ |
15538 | ~:ascii-format-drawer-function~ | ~org-ascii-format-drawer-function~ |
15539 | ~:ascii-format-inlinetask-function~ | ~org-ascii-format-inlinetask-function~ |
15540 | ~:ascii-headline-spacing~ | ~org-ascii-headline-spacing~ |
15541 | ~:ascii-indented-line-width~ | ~org-ascii-indented-line-width~ |
15542 | ~:ascii-inlinetask-width~ | ~org-ascii-inlinetask-width~ |
15543 | ~:ascii-inner-margin~ | ~org-ascii-inner-margin~ |
15544 | ~:ascii-links-to-notes~ | ~org-ascii-links-to-notes~ |
15545 | ~:ascii-list-margin~ | ~org-ascii-list-margin~ |
15546 | ~:ascii-paragraph-spacing~ | ~org-ascii-paragraph-spacing~ |
15547 | ~:ascii-quote-margin~ | ~org-ascii-quote-margin~ |
15548 | ~:ascii-table-keep-all-vertical-lines~ | ~org-ascii-table-keep-all-vertical-lines~ |
15549 | ~:ascii-table-use-ascii-art~ | ~org-ascii-table-use-ascii-art~ |
15550 | ~:ascii-table-widen-columns~ | ~org-ascii-table-widen-columns~ |
15551 | ~:ascii-text-width~ | ~org-ascii-text-width~ |
15552 | ~:ascii-underline~ | ~org-ascii-underline~ |
15553 | ~:ascii-verbatim-format~ | ~org-ascii-verbatim-format~ |
15555 **** Beamer specific properties
15560 | ~:beamer-theme~ | ~org-beamer-theme~ |
15561 | ~:beamer-column-view-format~ | ~org-beamer-column-view-format~ |
15562 | ~:beamer-environments-extra~ | ~org-beamer-environments-extra~ |
15563 | ~:beamer-frame-default-options~ | ~org-beamer-frame-default-options~ |
15564 | ~:beamer-outline-frame-options~ | ~org-beamer-outline-frame-options~ |
15565 | ~:beamer-outline-frame-title~ | ~org-beamer-outline-frame-title~ |
15566 | ~:beamer-subtitle-format~ | ~org-beamer-subtitle-format~ |
15568 **** HTML specific properties
15573 | ~:html-allow-name-attribute-in-anchors~ | ~org-html-allow-name-attribute-in-anchors~ |
15574 | ~:html-checkbox-type~ | ~org-html-checkbox-type~ |
15575 | ~:html-container~ | ~org-html-container-element~ |
15576 | ~:html-divs~ | ~org-html-divs~ |
15577 | ~:html-doctype~ | ~org-html-doctype~ |
15578 | ~:html-extension~ | ~org-html-extension~ |
15579 | ~:html-footnote-format~ | ~org-html-footnote-format~ |
15580 | ~:html-footnote-separator~ | ~org-html-footnote-separator~ |
15581 | ~:html-footnotes-section~ | ~org-html-footnotes-section~ |
15582 | ~:html-format-drawer-function~ | ~org-html-format-drawer-function~ |
15583 | ~:html-format-headline-function~ | ~org-html-format-headline-function~ |
15584 | ~:html-format-inlinetask-function~ | ~org-html-format-inlinetask-function~ |
15585 | ~:html-head-extra~ | ~org-html-head-extra~ |
15586 | ~:html-head-include-default-style~ | ~org-html-head-include-default-style~ |
15587 | ~:html-head-include-scripts~ | ~org-html-head-include-scripts~ |
15588 | ~:html-head~ | ~org-html-head~ |
15589 | ~:html-home/up-format~ | ~org-html-home/up-format~ |
15590 | ~:html-html5-fancy~ | ~org-html-html5-fancy~ |
15591 | ~:html-indent~ | ~org-html-indent~ |
15592 | ~:html-infojs-options~ | ~org-html-infojs-options~ |
15593 | ~:html-infojs-template~ | ~org-html-infojs-template~ |
15594 | ~:html-inline-image-rules~ | ~org-html-inline-image-rules~ |
15595 | ~:html-inline-images~ | ~org-html-inline-images~ |
15596 | ~:html-link-home~ | ~org-html-link-home~ |
15597 | ~:html-link-org-files-as-html~ | ~org-html-link-org-files-as-html~ |
15598 | ~:html-link-up~ | ~org-html-link-up~ |
15599 | ~:html-link-use-abs-url~ | ~org-html-link-use-abs-url~ |
15600 | ~:html-mathjax-options~ | ~org-html-mathjax-options~ |
15601 | ~:html-mathjax-template~ | ~org-html-mathjax-template~ |
15602 | ~:html-metadata-timestamp-format~ | ~org-html-metadata-timestamp-format~ |
15603 | ~:html-postamble-format~ | ~org-html-postamble-format~ |
15604 | ~:html-postamble~ | ~org-html-postamble~ |
15605 | ~:html-preamble-format~ | ~org-html-preamble-format~ |
15606 | ~:html-preamble~ | ~org-html-preamble~ |
15607 | ~:html-self-link-headlines~ | ~org-html-self-link-headlines~ |
15608 | ~:html-table-align-individual-field~ | ~de{org-html-table-align-individual-fields~ |
15609 | ~:html-table-attributes~ | ~org-html-table-default-attributes~ |
15610 | ~:html-table-caption-above~ | ~org-html-table-caption-above~ |
15611 | ~:html-table-data-tags~ | ~org-html-table-data-tags~ |
15612 | ~:html-table-header-tags~ | ~org-html-table-header-tags~ |
15613 | ~:html-table-row-tags~ | ~org-html-table-row-tags~ |
15614 | ~:html-table-use-header-tags-for-first-column~ | ~org-html-table-use-header-tags-for-first-column~ |
15615 | ~:html-tag-class-prefix~ | ~org-html-tag-class-prefix~ |
15616 | ~:html-text-markup-alist~ | ~org-html-text-markup-alist~ |
15617 | ~:html-todo-kwd-class-prefix~ | ~org-html-todo-kwd-class-prefix~ |
15618 | ~:html-toplevel-hlevel~ | ~org-html-toplevel-hlevel~ |
15619 | ~:html-use-infojs~ | ~org-html-use-infojs~ |
15620 | ~:html-validation-link~ | ~org-html-validation-link~ |
15621 | ~:html-viewport~ | ~org-html-viewport~ |
15622 | ~:html-xml-declaration~ | ~org-html-xml-declaration~ |
15624 **** LaTeX specific properties
15629 | ~:latex-active-timestamp-format~ | ~org-latex-active-timestamp-format~ |
15630 | ~:latex-caption-above~ | ~org-latex-caption-above~ |
15631 | ~:latex-classes~ | ~org-latex-classes~ |
15632 | ~:latex-class~ | ~org-latex-default-class~ |
15633 | ~:latex-compiler~ | ~org-latex-compiler~ |
15634 | ~:latex-default-figure-position~ | ~org-latex-default-figure-position~ |
15635 | ~:latex-default-table-environment~ | ~org-latex-default-table-environment~ |
15636 | ~:latex-default-table-mode~ | ~org-latex-default-table-mode~ |
15637 | ~:latex-diary-timestamp-format~ | ~org-latex-diary-timestamp-format~ |
15638 | ~:latex-footnote-defined-format~ | ~org-latex-footnote-defined-format~ |
15639 | ~:latex-footnote-separator~ | ~org-latex-footnote-separator~ |
15640 | ~:latex-format-drawer-function~ | ~org-latex-format-drawer-function~ |
15641 | ~:latex-format-headline-function~ | ~org-latex-format-headline-function~ |
15642 | ~:latex-format-inlinetask-function~ | ~org-latex-format-inlinetask-function~ |
15643 | ~:latex-hyperref-template~ | ~org-latex-hyperref-template~ |
15644 | ~:latex-image-default-height~ | ~org-latex-image-default-height~ |
15645 | ~:latex-image-default-option~ | ~org-latex-image-default-option~ |
15646 | ~:latex-image-default-width~ | ~org-latex-image-default-width~ |
15647 | ~:latex-images-centered~ | ~org-latex-images-centered~ |
15648 | ~:latex-inactive-timestamp-format~ | ~org-latex-inactive-timestamp-format~ |
15649 | ~:latex-inline-image-rules~ | ~org-latex-inline-image-rules~ |
15650 | ~:latex-link-with-unknown-path-format~ | ~org-latex-link-with-unknown-path-format~ |
15651 | ~:latex-listings-langs~ | ~org-latex-listings-langs~ |
15652 | ~:latex-listings-options~ | ~org-latex-listings-options~ |
15653 | ~:latex-listings~ | ~org-latex-listings~ |
15654 | ~:latex-minted-langs~ | ~org-latex-minted-langs~ |
15655 | ~:latex-minted-options~ | ~org-latex-minted-options~ |
15656 | ~:latex-prefer-user-labels~ | ~org-latex-prefer-user-labels~ |
15657 | ~:latex-subtitle-format~ | ~org-latex-subtitle-format~ |
15658 | ~:latex-subtitle-separate~ | ~org-latex-subtitle-separate~ |
15659 | ~:latex-table-scientific-notation~ | ~org-latex-table-scientific-notation~ |
15660 | ~:latex-tables-booktabs~ | ~org-latex-tables-booktabs~ |
15661 | ~:latex-tables-centered~ | ~org-latex-tables-centered~ |
15662 | ~:latex-text-markup-alist~ | ~org-latex-text-markup-alist~ |
15663 | ~:latex-title-command~ | ~org-latex-title-command~ |
15664 | ~:latex-toc-command~ | ~org-latex-toc-command~ |
15666 **** Markdown specific properties
15671 | ~:md-footnote-format~ | ~org-md-footnote-format~ |
15672 | ~:md-footnotes-section~ | ~org-md-footnotes-section~ |
15673 | ~:md-headline-style~ | ~org-md-headline-style~ |
15675 **** ODT specific properties
15680 | ~:odt-content-template-file~ | ~org-odt-content-template-file~ |
15681 | ~:odt-display-outline-level~ | ~org-odt-display-outline-level~ |
15682 | ~:odt-fontify-srcblocks~ | ~org-odt-fontify-srcblocks~ |
15683 | ~:odt-format-drawer-function~ | ~org-odt-format-drawer-function~ |
15684 | ~:odt-format-headline-function~ | ~org-odt-format-headline-function~ |
15685 | ~:odt-format-inlinetask-function~ | ~org-odt-format-inlinetask-function~ |
15686 | ~:odt-inline-formula-rules~ | ~org-odt-inline-formula-rules~ |
15687 | ~:odt-inline-image-rules~ | ~org-odt-inline-image-rules~ |
15688 | ~:odt-pixels-per-inch~ | ~org-odt-pixels-per-inch~ |
15689 | ~:odt-styles-file~ | ~org-odt-styles-file~ |
15690 | ~:odt-table-styles~ | ~org-odt-table-styles~ |
15691 | ~:odt-use-date-fields~ | ~org-odt-use-date-fields~ |
15693 **** Texinfo specific properties
15698 | ~:texinfo-active-timestamp-format~ | ~org-texinfo-active-timestamp-format~ |
15699 | ~:texinfo-classes~ | ~org-texinfo-classes~ |
15700 | ~:texinfo-class~ | ~org-texinfo-default-class~ |
15701 | ~:texinfo-table-default-markup~ | ~org-texinfo-table-default-markup~ |
15702 | ~:texinfo-diary-timestamp-format~ | ~org-texinfo-diary-timestamp-format~ |
15703 | ~:texinfo-filename~ | ~org-texinfo-filename~ |
15704 | ~:texinfo-format-drawer-function~ | ~org-texinfo-format-drawer-function~ |
15705 | ~:texinfo-format-headline-function~ | ~org-texinfo-format-headline-function~ |
15706 | ~:texinfo-format-inlinetask-function~ | ~org-texinfo-format-inlinetask-function~ |
15707 | ~:texinfo-inactive-timestamp-format~ | ~org-texinfo-inactive-timestamp-format~ |
15708 | ~:texinfo-link-with-unknown-path-format~ | ~org-texinfo-link-with-unknown-path-format~ |
15709 | ~:texinfo-node-description-column~ | ~org-texinfo-node-description-column~ |
15710 | ~:texinfo-table-scientific-notation~ | ~org-texinfo-table-scientific-notation~ |
15711 | ~:texinfo-tables-verbatim~ | ~org-texinfo-tables-verbatim~ |
15712 | ~:texinfo-text-markup-alist~ | ~org-texinfo-text-markup-alist~ |
15714 *** Publishing links
15716 :DESCRIPTION: Which links keep working after publishing?
15718 #+cindex: links, publishing
15720 To create a link from one Org file to another, you would use something
15721 like =[[file:foo.org][The foo]]= or simply =[[file:foo.org]]= (see [[*External Links]]). When
15722 published, this link becomes a link to =foo.html=. You can thus
15723 interlink the pages of your "Org web" project and the links will work
15724 as expected when you publish them to HTML. If you also publish the
15725 Org source file and want to link to it, use an =http= link instead of
15726 a =file:= link, because =file= links are converted to link to the
15727 corresponding =.html= file.
15729 You may also link to related files, such as images. Provided you are
15730 careful with relative file names, and provided you have also
15731 configured Org to upload the related files, these links will work too.
15732 See [[*Example: complex publishing configuration]], for an example of this
15735 Eventually, links between published documents can contain some search
15736 options (see [[*Search Options in File Links]]), which will be resolved to
15737 the appropriate location in the linked file. For example, once
15738 published to HTML, the following links all point to a dedicated anchor
15742 [[file:foo.org::*heading]]
15743 [[file:foo.org::#custom-id]]
15744 [[file:foo.org::target]]
15747 *** Generating a sitemap
15749 :DESCRIPTION: Generating a list of all pages.
15750 :ALT_TITLE: Site map
15752 #+cindex: sitemap, of published pages
15754 The following properties may be used to control publishing of
15755 a map of files for a given project.
15757 - ~:auto-sitemap~ ::
15759 When non-~nil~, publish a sitemap during
15760 ~org-publish-current-project~ or ~org-publish-all~.
15762 - ~:sitemap-filename~ ::
15764 Filename for output of sitemap. Defaults to =sitemap.org=, which
15765 becomes =sitemap.html=.
15767 - ~:sitemap-title~ ::
15769 Title of sitemap page. Defaults to name of file.
15771 - ~:sitemap-format-entry~ ::
15773 #+findex: org-publish-find-date
15774 #+findex: org-publish-find-property
15775 #+findex: org-publish-find-title
15776 With this option one can tell how a site-map entry is formatted in
15777 the site-map. It is a function called with three arguments: the
15778 file or directory name relative to base directory of the project,
15779 the site-map style and the current project. It is expected to
15780 return a string. Default value turns file names into links and use
15781 document titles as descriptions. For specific formatting needs, one
15782 can use ~org-publish-find-date~, ~org-publish-find-title~ and
15783 ~org-publish-find-property~, to retrieve additional information
15784 about published documents.
15786 - ~:sitemap-function~ ::
15788 Plug-in function to use for generation of the sitemap. It is called
15789 with two arguments: the title of the site-map and a representation
15790 of the files and directories involved in the project as a nested
15791 list, which can further be transformed using ~org-list-to-generic~,
15792 ~org-list-to-subtree~ and alike. Default value generates a plain
15793 list of links to all files in the project.
15795 - ~:sitemap-sort-folders~ ::
15797 Where folders should appear in the sitemap. Set this to ~first~
15798 (default) or ~last~ to display folders first or last, respectively.
15799 When set to ~ignore~, folders are ignored altogether. Any other
15800 value mixes files and folders. This variable has no effect when
15801 site-map style is ~tree~.
15803 - ~:sitemap-sort-files~ ::
15805 How the files are sorted in the site map. Set this to
15806 ~alphabetically~ (default), ~chronologically~ or
15807 ~anti-chronologically~. ~chronologically~ sorts the files with
15808 older date first while ~anti-chronologically~ sorts the files with
15809 newer date first. ~alphabetically~ sorts the files alphabetically.
15810 The date of a file is retrieved with ~org-publish-find-date~.
15812 - ~:sitemap-ignore-case~ ::
15814 Should sorting be case-sensitive? Default ~nil~.
15816 - ~:sitemap-file-entry-format~ ::
15818 With this option one can tell how a sitemap's entry is formatted in
15819 the sitemap. This is a format string with some escape sequences:
15820 ~%t~ stands for the title of the file, ~%a~ stands for the author of
15821 the file and ~%d~ stands for the date of the file. The date is
15822 retrieved with the ~org-publish-find-date~ function and formatted
15823 with ~org-publish-sitemap-date-format~. Default ~%t~.
15825 - ~:sitemap-date-format~ ::
15827 Format string for the ~format-time-string~ function that tells how
15828 a sitemap entry's date is to be formatted. This property bypasses
15829 ~org-publish-sitemap-date-format~ which defaults to ~%Y-%m-%d~.
15831 *** Generating an index
15833 :DESCRIPTION: An index that reaches across pages.
15835 #+cindex: index, in a publishing project
15837 Org mode can generate an index across the files of a publishing project.
15841 When non-~nil~, generate in index in the file =theindex.org= and
15842 publish it as =theindex.html=.
15844 The file is created when first publishing a project with the
15845 ~:makeindex~ set. The file only contains a statement =#+INCLUDE:
15846 "theindex.inc"=. You can then build around this include statement by
15847 adding a title, style information, etc.
15849 #+cindex: @samp{INDEX}, keyword
15850 Index entries are specified with =INDEX= keyword. An entry that
15851 contains an exclamation mark creates a sub item.
15854 ,*** Curriculum Vitae
15856 ,#+INDEX: Application!CV
15861 :DESCRIPTION: How to get files up on the server.
15866 For those people already utilizing third party sync tools such as
15867 Rsync or Unison, it might be preferable not to use the built-in remote
15868 publishing facilities of Org mode which rely heavily on Tramp. Tramp,
15869 while very useful and powerful, tends not to be so efficient for
15870 multiple file transfer and has been known to cause problems under
15873 Specialized synchronization utilities offer several advantages. In
15874 addition to timestamp comparison, they also do content and
15875 permissions/attribute checks. For this reason you might prefer to
15876 publish your web to a local directory---possibly even /in place/ with
15877 your Org files---and then use Unison or Rsync to do the
15878 synchronization with the remote host.
15880 Since Unison, for example, can be configured as to which files to
15881 transfer to a certain remote destination, it can greatly simplify the
15882 project publishing definition. Simply keep all files in the correct
15883 location, process your Org files with ~org-publish~ and let the
15884 synchronization tool do the rest. You do not need, in this scenario,
15885 to include attachments such as JPG, CSS or PNG files in the project
15886 definition since the third-party tool syncs them.
15888 Publishing to a local directory is also much faster than to a remote
15889 one, so that you can afford more easily to republish entire projects.
15890 If you set ~org-publish-use-timestamps-flag~ to ~nil~, you gain the
15891 main benefit of re-including any changed external files such as source
15892 example files you might include with =INCLUDE= keyword. The timestamp
15893 mechanism in Org is not smart enough to detect if included files have
15896 ** Sample Configuration
15898 :DESCRIPTION: Example projects.
15901 Below we provide two example configurations. The first one is
15902 a simple project publishing only a set of Org files. The second
15903 example is more complex, with a multi-component project.
15905 *** Example: simple publishing configuration
15907 :DESCRIPTION: One-component publishing.
15908 :ALT_TITLE: Simple example
15911 This example publishes a set of Org files to the =public_html=
15912 directory on the local machine.
15914 #+begin_src emacs-lisp
15915 (setq org-publish-project-alist
15917 :base-directory "~/org/"
15918 :publishing-directory "~/public_html"
15919 :section-numbers nil
15920 :table-of-contents nil
15921 :style "<link rel=\"stylesheet\"
15922 href=\"../other/mystyle.css\"
15923 type=\"text/css\"/>")))
15926 *** Example: complex publishing configuration
15928 :DESCRIPTION: A multi-component publishing example.
15929 :ALT_TITLE: Complex example
15932 This more complicated example publishes an entire website, including
15933 Org files converted to HTML, image files, Emacs Lisp source code, and
15934 style sheets. The publishing directory is remote and private files
15937 To ensure that links are preserved, care should be taken to replicate
15938 your directory structure on the web server, and to use relative file
15939 paths. For example, if your Org files are kept in =~/org/= and your
15940 publishable images in =~/images/=, you would link to an image with
15942 : file:../images/myimage.png
15944 On the web server, the relative path to the image should be the same.
15945 You can accomplish this by setting up an =images/= folder in the right
15946 place on the web server, and publishing images to it.
15948 #+begin_src emacs-lisp
15949 (setq org-publish-project-alist
15951 :base-directory "~/org/"
15952 :base-extension "org"
15953 :publishing-directory "/ssh:user@host:~/html/notebook/"
15954 :publishing-function org-html-publish-to-html
15955 :exclude "PrivatePage.org" ;; regexp
15957 :section-numbers nil
15959 :html-head "<link rel=\"stylesheet\"
15960 href=\"../other/mystyle.css\" type=\"text/css\"/>"
15964 :base-directory "~/images/"
15965 :base-extension "jpg\\|gif\\|png"
15966 :publishing-directory "/ssh:user@host:~/html/images/"
15967 :publishing-function org-publish-attachment)
15970 :base-directory "~/other/"
15971 :base-extension "css\\|el"
15972 :publishing-directory "/ssh:user@host:~/html/other/"
15973 :publishing-function org-publish-attachment)
15974 ("website" :components ("orgfiles" "images" "other"))))
15977 ** Triggering Publication
15979 :DESCRIPTION: Publication commands.
15982 Once properly configured, Org can publish with the following commands:
15984 - {{{kbd(C-c C-e X)}}} (~org-publish~) ::
15986 #+kindex: C-c C-e X
15987 #+findex: org-publish
15988 Prompt for a specific project and publish all files that belong to
15991 - {{{kbd(C-c C-e P)}}} (~org-publish-current-project~) ::
15993 #+kindex: C-c C-e P
15994 #+findex: org-publish-current-project
15995 Publish the project containing the current file.
15997 - {{{kbd(C-c C-e F)}}} (~org-publish-current-file~) ::
15999 #+kindex: C-c C-e F
16000 #+findex: org-publish-current-file
16001 Publish only the current file.
16003 - {{{kbd(C-c C-e E)}}} (~org-publish-all~) ::
16005 #+kindex: C-c C-e E
16006 #+findex: org-publish-all
16007 Publish every project.
16009 #+vindex: org-publish-use-timestamps-flag
16010 Org uses timestamps to track when a file has changed. The above
16011 functions normally only publish changed files. You can override this
16012 and force publishing of all files by giving a prefix argument to any
16013 of the commands above, or by customizing the variable
16014 ~org-publish-use-timestamps-flag~. This may be necessary in
16015 particular if files include other files via =SETUPFILE= or =INCLUDE=
16018 * Working with Source Code
16020 :DESCRIPTION: Export, evaluate, and tangle code blocks.
16022 #+cindex: source code, working with
16024 Source code here refers to any plain text collection of computer
16025 instructions, possibly with comments, written using a human-readable
16026 programming language. Org can manage source code in an Org document
16027 when the source code is identified with begin and end markers.
16028 Working with source code begins with identifying source code blocks.
16029 A source code block can be placed almost anywhere in an Org document;
16030 it is not restricted to the preamble or the end of the document.
16031 However, Org cannot manage a source code block if it is placed inside
16032 an Org comment or within a fixed width section.
16034 Here is an example source code block in the Emacs Lisp language:
16037 ,#+BEGIN_SRC emacs-lisp
16038 (defun org-xor (a b)
16044 Org can manage the source code in the block delimited by =#+BEGIN_SRC=
16045 ... =#+END_SRC= in several ways that can simplify housekeeping tasks
16046 essential to modern source code maintenance. Org can edit, format,
16047 extract, export, and publish source code blocks. Org can also compile
16048 and execute a source code block, then capture the results. The Org
16049 mode literature sometimes refers to source code blocks as /live code/
16050 blocks because they can alter the content of the Org document or the
16051 material that it exports. Users can control how live they want each
16052 source code block by tweaking the header arguments (see [[*Using
16053 Header Arguments]]) for compiling, execution, extraction, and
16056 Source code blocks are one of many Org block types, which also include
16057 "center", "comment", "dynamic", "example", "export", "quote",
16058 "special", and "verse". This section pertains to blocks between
16059 =#+BEGIN_SRC= and =#+END_SRC=.
16061 For editing and formatting a source code block, Org uses an
16062 appropriate Emacs major mode that includes features specifically
16063 designed for source code in that language.
16065 Org can extract one or more source code blocks and write them to one
16066 or more source files---a process known as /tangling/ in literate
16067 programming terminology.
16069 For exporting and publishing, Org's back-ends can format a source code
16070 block appropriately, often with native syntax highlighting.
16072 For executing and compiling a source code block, the user can
16073 configure Org to select the appropriate compiler. Org provides
16074 facilities to collect the result of the execution or compiler output,
16075 insert it into the Org document, and/or export it. In addition to
16076 text results, Org can insert links to other data types, including
16077 audio, video, and graphics. Org can also link a compiler error
16078 message to the appropriate line in the source code block.
16080 An important feature of Org's management of source code blocks is the
16081 ability to pass variables, functions, and results to one another using
16082 a common syntax for source code blocks in any language. Although most
16083 literate programming facilities are restricted to one language or
16084 another, Org's language-agnostic approach lets the literate programmer
16085 match each programming task with the appropriate computer language and
16086 to mix them all together in a single Org document. This
16087 interoperability among languages explains why Org's source code
16088 management facility was named /Org Babel/ by its originators, Eric
16089 Schulte and Dan Davison.
16091 Org mode fulfills the promise of easy verification and maintenance of
16092 publishing reproducible research by keeping text, data, code,
16093 configuration settings of the execution environment, the results of
16094 the execution, and associated narratives, claims, references, and
16095 internal and external links in a single Org document.
16097 Details of Org's facilities for working with source code are described
16098 in the following sections.
16100 ** Structure of Code Blocks
16102 :DESCRIPTION: Code block syntax described.
16104 #+cindex: code block, structure
16105 #+cindex: source code, block structure
16106 #+cindex: @samp{NAME} keyword, in source blocks
16107 #+cindex: @samp{BEGIN_SRC}
16109 Org offers two ways to structure source code in Org documents: in
16110 a source code block, and directly inline. Both specifications are
16113 A source code block conforms to this structure:
16117 ,#+BEGIN_SRC <language> <switches> <header arguments>
16122 Do not be put-off by having to remember the source block syntax. Org
16123 mode offers a command for wrapping existing text in a block (see
16124 [[*Structure Templates]]). Org also works with other completion systems
16125 in Emacs, some of which predate Org and have custom domain-specific
16126 languages for defining templates. Regular use of templates reduces
16127 errors, increases accuracy, and maintains consistency.
16129 #+cindex: source code, inline
16130 An inline code block conforms to this structure:
16132 : src_<language>{<body>}
16134 #+texinfo: @noindent
16137 : src_<language>[<header arguments>]{<body>}
16139 - =#+NAME: <name>= ::
16141 Optional. Names the source block so it can be called, like
16142 a function, from other source blocks or inline code to evaluate or
16143 to capture the results. Code from other blocks, other files, and
16144 from table formulas (see [[*The Spreadsheet]]) can use the name to
16145 reference a source block. This naming serves the same purpose as
16146 naming Org tables. Org mode requires unique names. For duplicate
16147 names, Org mode's behavior is undefined.
16149 - =#+BEGIN_SRC= ... =#+END_SRC= ::
16151 Mandatory. They mark the start and end of a block that Org
16152 requires. The =#+BEGIN_SRC= line takes additional arguments, as
16157 #+cindex: language, in code blocks
16158 Mandatory. It is the identifier of the source code language in the
16159 block. See [[*Languages]], for identifiers of supported languages.
16163 #+cindex: switches, in code blocks
16164 Optional. Switches provide finer control of the code execution,
16165 export, and format (see the discussion of switches in [[*Literal
16168 - =<header arguments>= ::
16170 #+cindex: header arguments, in code blocks
16171 Optional. Heading arguments control many aspects of evaluation,
16172 export and tangling of code blocks (see [[*Using Header Arguments]]).
16173 Using Org's properties feature, header arguments can be selectively
16174 applied to the entire buffer or specific sub-trees of the Org
16179 Source code in the dialect of the specified language identifier.
16181 ** Using Header Arguments
16183 :DESCRIPTION: Different ways to set header arguments.
16186 Org comes with many header arguments common to all languages. New
16187 header arguments are added for specific languages as they become
16188 available for use in source code blocks. A header argument is
16189 specified with an initial colon followed by the argument's name in
16192 Since header arguments can be set in several ways, Org prioritizes
16193 them in case of overlaps or conflicts by giving local settings
16194 a higher priority. Header values in function calls, for example,
16195 override header values from global defaults.
16197 *** System-wide header arguments
16201 #+vindex: org-babel-default-header-args
16203 #+vindex: org-babel-default-header-args
16204 System-wide values of header arguments can be specified by customizing
16205 the ~org-babel-default-header-args~ variable, which defaults to the
16210 :results => "replace"
16216 The example below sets =:noweb= header arguments to =yes=, which makes
16217 Org expand =:noweb= references by default.
16219 #+begin_src emacs-lisp
16220 (setq org-babel-default-header-args
16221 (cons '(:noweb . "yes")
16222 (assq-delete-all :noweb org-babel-default-header-args)))
16225 #+cindex: language specific default header arguments
16226 #+cindex: default header arguments per language
16227 Each language can have separate default header arguments by
16228 customizing the variable ~org-babel-default-header-args:<LANG>~, where
16229 {{{var(<LANG>)}}} is the name of the language. For details, see the
16230 language-specific online documentation at
16231 https://orgmode.org/worg/org-contrib/babel/.
16233 *** Header arguments in Org mode properties
16238 For header arguments applicable to the buffer, use =PROPERTY= keyword
16239 anywhere in the Org file (see [[*Property Syntax]]).
16241 The following example makes all the R code blocks execute in the same
16242 session. Setting =:results= to =silent= ignores the results of
16243 executions for all blocks, not just R code blocks; no results inserted
16247 ,#+PROPERTY: header-args:R :session *R*
16248 ,#+PROPERTY: header-args :results silent
16251 #+vindex: org-use-property-inheritance
16252 Header arguments set through Org's property drawers (see [[*Property
16253 Syntax]]) apply at the sub-tree level on down. Since these property
16254 drawers can appear anywhere in the file hierarchy, Org uses outermost
16255 call or source block to resolve the values. Org ignores
16256 ~org-use-property-inheritance~ setting.
16258 In this example, =:cache= defaults to =yes= for all code blocks in the
16264 :header-args: :cache yes
16268 #+kindex: C-c C-x p
16269 #+findex: org-set-property
16270 Properties defined through ~org-set-property~ function, bound to
16271 {{{kbd(C-c C-x p)}}}, apply to all active languages. They override
16272 properties set in ~org-babel-default-header-args~.
16274 #+cindex: language specific header arguments properties
16275 #+cindex: header arguments per language
16276 Language-specific header arguments are also read from properties
16277 =header-args:<LANG>= where {{{var(<LANG>)}}} is the language
16278 identifier. For example,
16283 :header-args:clojure: :session *clojure-1*
16284 :header-args:R: :session *R*
16288 :header-args:clojure: :session *clojure-2*
16292 #+texinfo: @noindent
16293 would force separate sessions for Clojure blocks in =Heading= and
16294 =Subheading=, but use the same session for all R blocks. Blocks in
16295 =Subheading= inherit settings from =Heading=.
16297 *** Code block specific header arguments
16302 Header arguments are most commonly set at the source code block level,
16303 on the =#+BEGIN_SRC= line. Arguments set at this level take
16304 precedence over those set in the ~org-babel-default-header-args~
16305 variable, and also those set as header properties.
16307 In the following example, setting =:results= to =silent= makes it
16308 ignore results of the code execution. Setting =:exports= to =code=
16309 exports only the body of the code block to HTML or LaTeX.
16313 ,#+BEGIN_SRC haskell :results silent :exports code :var n=0
16315 fac n = n * fac (n-1)
16319 The same header arguments in an inline code block:
16321 : src_haskell[:exports both]{fac 5}
16323 #+cindex: @samp{HEADER}, keyword
16324 Code block header arguments can span multiple lines using =#+HEADER:=
16325 on each line. Note that Org currently accepts the plural spelling of
16326 =#+HEADER:= only as a convenience for backward-compatibility. It may
16327 be removed at some point.
16329 Multi-line header arguments on an unnamed code block:
16332 ,#+HEADER: :var data1=1
16333 ,#+BEGIN_SRC emacs-lisp :var data2=2
16334 (message "data1:%S, data2:%S" data1 data2)
16341 Multi-line header arguments on a named code block:
16344 ,#+NAME: named-block
16345 ,#+HEADER: :var data=2
16346 ,#+BEGIN_SRC emacs-lisp
16347 (message "data:%S" data)
16350 ,#+RESULTS: named-block
16354 *** Header arguments in function calls
16359 Header arguments in function calls are the most specific and override
16360 all other settings in case of an overlap. They get the highest
16361 priority. Two =#+CALL:= examples are shown below. For the complete
16362 syntax of =CALL= keyword, see [[*Evaluating Code Blocks]].
16364 In this example, =:exports results= header argument is applied to the
16365 evaluation of the =#+CALL:= line.
16367 : #+CALL: factorial(n=5) :exports results
16369 In this example, =:session special= header argument is applied to the
16370 evaluation of =factorial= code block.
16372 : #+CALL: factorial[:session special](n=5)
16374 ** Environment of a Code Block
16376 :DESCRIPTION: Arguments, sessions, working directory...
16379 *** Passing arguments
16384 #+cindex: passing arguments to code blocks
16385 #+cindex: arguments, in code blocks
16386 #+cindex: @samp{var}, header argument
16387 Use =var= for passing arguments to source code blocks. The specifics
16388 of variables in code blocks vary by the source language and are
16389 covered in the language-specific documentation. The syntax for =var=,
16390 however, is the same for all languages. This includes declaring
16391 a variable, and assigning a default value.
16393 The following syntax is used to pass arguments to code blocks using
16394 the =var= header argument.
16398 #+texinfo: @noindent
16399 {{{var(NAME)}}} is the name of the variable bound in the code block
16400 body. {{{var(ASSIGN)}}} is a literal value, such as a string,
16401 a number, a reference to a table, a list, a literal example, another
16402 code block---with or without arguments---or the results of evaluating
16405 Here are examples of passing values by reference:
16409 A table named with a =NAME= keyword.
16412 ,#+NAME: example-table
16418 ,#+NAME: table-length
16419 ,#+BEGIN_SRC emacs-lisp :var table=example-table
16423 ,#+RESULTS: table-length
16427 When passing a table, you can treat specially the row, or the
16428 column, containing labels for the columns, or the rows, in the
16431 #+cindex: @samp{colnames}, header argument
16432 The =colnames= header argument accepts =yes=, =no=, or =nil=
16433 values. The default value is =nil=: if an input table has column
16434 names---because the second row is a horizontal rule---then Org
16435 removes the column names, processes the table, puts back the
16436 column names, and then writes the table to the results block.
16437 Using =yes=, Org does the same to the first row, even if the
16438 initial table does not contain any horizontal rule. When set to
16439 =no=, Org does not pre-process column names at all.
16448 ,#+BEGIN_SRC python :var tab=less-cols :colnames nil
16449 return [[val + '*' for val in row] for row in tab]
16459 #+cindex: @samp{rownames}, header argument
16460 Similarly, the =rownames= header argument can take two values: =yes=
16461 or =no=. When set to =yes=, Org removes the first column, processes
16462 the table, puts back the first column, and then writes the table to
16463 the results block. The default is =no=, which means Org does not
16464 pre-process the first column. Note that Emacs Lisp code blocks
16465 ignore =rownames= header argument because of the ease of
16466 table-handling in Emacs.
16469 ,#+NAME: with-rownames
16470 | one | 1 | 2 | 3 | 4 | 5 |
16471 | two | 6 | 7 | 8 | 9 | 10 |
16473 ,#+BEGIN_SRC python :var tab=with-rownames :rownames yes
16474 return [[val + 10 for val in row] for row in tab]
16478 | one | 11 | 12 | 13 | 14 | 15 |
16479 | two | 16 | 17 | 18 | 19 | 20 |
16484 A simple named list.
16487 ,#+NAME: example-list
16493 ,#+BEGIN_SRC emacs-lisp :var x=example-list
16501 Note that only the top level list items are passed along. Nested
16502 list items are ignored.
16504 - code block without arguments ::
16506 A code block name, as assigned by =NAME= keyword from the example
16507 above, optionally followed by parentheses.
16510 ,#+BEGIN_SRC emacs-lisp :var length=table-length()
16518 - code block with arguments ::
16520 A code block name, as assigned by =NAME= keyword, followed by
16521 parentheses and optional arguments passed within the parentheses.
16525 ,#+BEGIN_SRC emacs-lisp :var input=8
16533 ,#+BEGIN_SRC emacs-lisp :var input=double(input=1)
16537 ,#+RESULTS: squared
16541 - literal example ::
16543 A literal example block named with a =NAME= keyword.
16546 ,#+NAME: literal-example
16552 ,#+NAME: read-literal-example
16553 ,#+BEGIN_SRC emacs-lisp :var x=literal-example
16554 (concatenate #'string x " for you.")
16557 ,#+RESULTS: read-literal-example
16558 : A literal example
16559 : on two lines for you.
16562 Indexing variable values enables referencing portions of a variable.
16563 Indexes are 0 based with negative values counting backwards from the
16564 end. If an index is separated by commas then each subsequent section
16565 indexes as the next dimension. Note that this indexing occurs
16566 /before/ other table-related header arguments are applied, such as
16567 =hlines=, =colnames= and =rownames=. The following example assigns
16568 the last cell of the first row the table =example-table= to the
16572 ,#+NAME: example-table
16578 ,#+BEGIN_SRC emacs-lisp :var data=example-table[0,-1]
16586 Two integers separated by a colon reference a range of variable
16587 values. In that case the entire inclusive range is referenced. For
16588 example the following assigns the middle three rows of =example-table=
16592 ,#+NAME: example-table
16599 ,#+BEGIN_SRC emacs-lisp :var data=example-table[1:3]
16609 To pick the entire range, use an empty index, or the single character
16610 =*=. =0:-1= does the same thing. Example below shows how to
16611 reference the first column only.
16614 ,#+NAME: example-table
16620 ,#+BEGIN_SRC emacs-lisp :var data=example-table[,0]
16628 Index referencing can be used for tables and code blocks. Index
16629 referencing can handle any number of dimensions. Commas delimit
16630 multiple dimensions, as shown below.
16634 ,#+BEGIN_SRC emacs-lisp
16635 '(((1 2 3) (4 5 6) (7 8 9))
16636 ((10 11 12) (13 14 15) (16 17 18))
16637 ((19 20 21) (22 23 24) (25 26 27)))
16640 ,#+BEGIN_SRC emacs-lisp :var data=3D[1,,1]
16648 Note that row names and column names are not removed prior to variable
16649 indexing. You need to take them into account, even when =colnames= or
16650 =rownames= header arguments remove them.
16652 Emacs lisp code can also set the values for variables. To
16653 differentiate a value from Lisp code, Org interprets any value
16654 starting with =(=, =[=, ='= or =`= as Emacs Lisp code. The result of
16655 evaluating that code is then assigned to the value of that variable.
16656 The following example shows how to reliably query and pass the file
16657 name of the Org mode buffer to a code block using headers. We need
16658 reliability here because the file's name could change once the code in
16659 the block starts executing.
16662 ,#+BEGIN_SRC sh :var filename=(buffer-file-name) :exports both
16667 Note that values read from tables and lists are not mistakenly
16668 evaluated as Emacs Lisp code, as illustrated in the following example.
16674 ,#+HEADER: :var data=table[0,0]
16688 #+cindex: using sessions in code blocks
16689 #+cindex: @samp{session}, header argument
16690 Two code blocks can share the same environment. The =session= header
16691 argument is for running multiple source code blocks under one session.
16692 Org runs code blocks with the same session name in the same
16693 interpreter process.
16697 Default. Each code block gets a new interpreter process to execute.
16698 The process terminates once the block is evaluated.
16700 - {{{var(STRING)}}} ::
16702 Any string besides =none= turns that string into the name of that
16703 session. For example, =:session STRING= names it =STRING=. If
16704 =session= has no value, then the session name is derived from the
16705 source language identifier. Subsequent blocks with the same source
16706 code language use the same session. Depending on the language,
16707 state variables, code from other blocks, and the overall interpreted
16708 environment may be shared. Some interpreted languages support
16709 concurrent sessions when subsequent source code language blocks
16710 change session names.
16712 Only languages that provide interactive evaluation can have session
16713 support. Not all languages provide this support, such as C and ditaa.
16714 Even languages, such as Python and Haskell, that do support
16715 interactive evaluation impose limitations on allowable language
16716 constructs that can run interactively. Org inherits those limitations
16717 for those code blocks running in a session.
16719 *** Choosing a working directory
16724 #+cindex: working directory, in a code block
16725 #+cindex: @samp{dir}, header argument
16726 The =dir= header argument specifies the default directory during code
16727 block execution. If it is absent, then the directory associated with
16728 the current buffer is used. In other words, supplying =:dir PATH=
16729 temporarily has the same effect as changing the current directory with
16730 {{{kbd(M-x cd PATH)}}}, and then not setting =dir=. Under the
16731 surface, =dir= simply sets the value of the Emacs variable
16732 ~default-directory~.
16734 For example, to save the plot file in the =Work/= folder of the home
16735 directory---notice tilde is expanded:
16738 ,#+BEGIN_SRC R :file myplot.png :dir ~/Work
16739 matplot(matrix(rnorm(100), 10), type="l")
16743 To evaluate the code block on a remote machine, supply a remote
16744 directory name using Tramp syntax. For example:
16747 ,#+BEGIN_SRC R :file plot.png :dir /scp:dand@yakuba.princeton.edu:
16748 plot(1:10, main=system("hostname", intern=TRUE))
16752 Org first captures the text results as usual for insertion in the Org
16753 file. Then Org also inserts a link to the remote file, thanks to
16754 Emacs Tramp. Org constructs the remote path to the file name from
16755 =dir= and ~default-directory~, as illustrated here:
16757 : [[file:/scp:dand@yakuba.princeton.edu:/home/dand/plot.png][plot.png]]
16759 When =dir= is used with =session=, Org sets the starting directory for
16760 a new session. But Org does not alter the directory of an already
16763 Do not use =dir= with =:exports results= or with =:exports both= to
16764 avoid Org inserting incorrect links to remote files. That is because
16765 Org does not expand ~default directory~ to avoid some underlying
16766 portability issues.
16768 *** Inserting headers and footers
16773 #+cindex: headers, in code blocks
16774 #+cindex: footers, in code blocks
16775 #+cindex: @samp{prologue}, header argument
16776 The =prologue= header argument is for appending to the top of the code
16777 block for execution, like a reset instruction. For example, you may
16778 use =:prologue "reset"= in a Gnuplot code block or, for every such
16781 #+begin_src emacs-lisp
16782 (add-to-list 'org-babel-default-header-args:gnuplot
16783 '((:prologue . "reset")))
16787 #+cindex: @samp{epilogue}, header argument
16788 Likewise, the value of the =epilogue= header argument is for appending
16789 to the end of the code block for execution.
16791 ** Evaluating Code Blocks
16793 :DESCRIPTION: Place results of evaluation in the Org buffer.
16795 #+cindex: code block, evaluating
16796 #+cindex: source code, evaluating
16797 #+cindex: @samp{RESULTS}, keyword
16799 A note about security: With code evaluation comes the risk of harm.
16800 Org safeguards by prompting for user's permission before executing any
16801 code in the source block. To customize this safeguard, or disable it,
16802 see [[*Code Evaluation and Security Issues]].
16804 *** How to evaluate source code
16809 Org captures the results of the code block evaluation and inserts them
16810 in the Org file, right after the code block. The insertion point is
16811 after a newline and the =RESULTS= keyword. Org creates the =RESULTS=
16812 keyword if one is not already there.
16814 By default, Org enables only Emacs Lisp code blocks for execution.
16815 See [[*Languages]] to enable other languages.
16818 #+kindex: C-c C-v e
16819 #+findex: org-babel-execute-src-block
16820 Org provides many ways to execute code blocks. {{{kbd(C-c C-c)}}} or
16821 {{{kbd(C-c C-v e)}}} with the point on a code block[fn:140] calls the
16822 ~org-babel-execute-src-block~ function, which executes the code in the
16823 block, collects the results, and inserts them in the buffer.
16825 #+cindex: @samp{CALL}, keyword
16826 #+vindex: org-babel-inline-result-wrap
16827 By calling a named code block[fn:141] from an Org mode buffer or
16828 a table. Org can call the named code blocks from the current Org mode
16829 buffer or from the "Library of Babel" (see [[*Library of Babel]]).
16831 The syntax for =CALL= keyword is:
16834 ,#+CALL: <name>(<arguments>)
16835 ,#+CALL: <name>[<inside header arguments>](<arguments>) <end header arguments>
16838 The syntax for inline named code blocks is:
16841 ... call_<name>(<arguments>) ...
16842 ... call_<name>[<inside header arguments>](<arguments>)[<end header arguments>] ...
16845 When inline syntax is used, the result is wrapped based on the
16846 variable ~org-babel-inline-result-wrap~, which by default is set to
16847 ~"=%s="~ to produce verbatim text suitable for markup.
16851 This is the name of the code block (see [[*Structure of Code Blocks]])
16852 to be evaluated in the current document. If the block is located in
16853 another file, start =<name>= with the file name followed by
16854 a colon. For example, in order to execute a block named =clear-data=
16855 in =file.org=, you can write the following:
16857 : #+CALL: file.org:clear-data()
16861 Org passes arguments to the code block using standard function call
16862 syntax. For example, a =#+CALL:= line that passes =4= to a code
16863 block named =double=, which declares the header argument =:var n=2=,
16864 would be written as:
16866 : #+CALL: double(n=4)
16868 #+texinfo: @noindent
16869 Note how this function call syntax is different from the header
16872 - =<inside header arguments>= ::
16874 Org passes inside header arguments to the named code block using the
16875 header argument syntax. Inside header arguments apply to code block
16876 evaluation. For example, =[:results output]= collects results
16877 printed to stdout during code execution of that block. Note how
16878 this header argument syntax is different from the function call
16881 - =<end header arguments>= ::
16883 End header arguments affect the results returned by the code block.
16884 For example, =:results html= wraps the results in a =#+BEGIN_EXPORT
16885 html= block before inserting the results in the Org buffer.
16887 *** Limit code block evaluation
16892 #+cindex: @samp{eval}, header argument
16893 #+cindex: control code block evaluation
16894 The =eval= header argument can limit evaluation of specific code
16895 blocks and =CALL= keyword. It is useful for protection against
16896 evaluating untrusted code blocks by prompting for a confirmation.
16898 - =never= or =no= ::
16900 Org never evaluates the source code.
16904 Org prompts the user for permission to evaluate the source code.
16906 - =never-export= or =no-export= ::
16908 Org does not evaluate the source code when exporting, yet the user
16909 can evaluate it interactively.
16911 - =query-export= ::
16913 Org prompts the user for permission to evaluate the source code
16916 If =eval= header argument is not set, then Org determines whether to
16917 evaluate the source code from the ~org-confirm-babel-evaluate~
16918 variable (see [[*Code Evaluation and Security Issues]]).
16920 *** Cache results of evaluation
16925 #+cindex: @samp{cache}, header argument
16926 #+cindex: cache results of code evaluation
16927 The =cache= header argument is for caching results of evaluating code
16928 blocks. Caching results can avoid re-evaluating a code block that
16929 have not changed since the previous run. To benefit from the cache
16930 and avoid redundant evaluations, the source block must have a result
16931 already present in the buffer, and neither the header
16932 arguments---including the value of =var= references---nor the text of
16933 the block itself has changed since the result was last computed. This
16934 feature greatly helps avoid long-running calculations. For some edge
16935 cases, however, the cached results may not be reliable.
16937 The caching feature is best for when code blocks are pure functions,
16938 that is functions that return the same value for the same input
16939 arguments (see [[*Environment of a Code Block]]), and that do not have
16940 side effects, and do not rely on external variables other than the
16941 input arguments. Functions that depend on a timer, file system
16942 objects, and random number generators are clearly unsuitable for
16945 A note of warning: when =cache= is used in a session, caching may
16946 cause unexpected results.
16948 When the caching mechanism tests for any source code changes, it does
16949 not expand Noweb style references (see [[*Noweb Reference Syntax]]). For
16950 reasons why, see http://thread.gmane.org/gmane.emacs.orgmode/79046.
16952 The =cache= header argument can have one of two values: =yes= or =no=.
16956 Default. No caching of results; code block evaluated every time.
16960 Whether to run the code or return the cached results is determined
16961 by comparing the SHA1 hash value of the combined code block and
16962 arguments passed to it. This hash value is packed on the
16963 =#+RESULTS:= line from previous evaluation. When hash values match,
16964 Org does not evaluate the code block. When hash values mismatch,
16965 Org evaluates the code block, inserts the results, recalculates the
16966 hash value, and updates =#+RESULTS:= line.
16968 In this example, both functions are cached. But =caller= runs only if
16969 the result from =random= has changed since the last run.
16973 ,#+BEGIN_SRC R :cache yes
16977 ,#+RESULTS[a2a72cd647ad44515fab62e144796432793d68e1]: random
16981 ,#+BEGIN_SRC emacs-lisp :var x=random :cache yes
16985 ,#+RESULTS[bec9c8724e397d5df3b696502df3ed7892fc4f5f]: caller
16989 ** Results of Evaluation
16991 :DESCRIPTION: Choosing a results type, post-processing...
16993 #+cindex: code block, results of evaluation
16994 #+cindex: source code, results of evaluation
16996 #+cindex: @samp{results}, header argument
16997 How Org handles results of a code block execution depends on many
16998 header arguments working together. The primary determinant, however,
16999 is the =results= header argument. It accepts four classes of options.
17000 Each code block can take only one option per class:
17004 For how the results should be collected from the code block;
17008 For which type of result the code block will return; affects how Org
17009 processes and inserts results in the Org buffer;
17013 For the result; affects how Org processes and inserts results in the
17018 For processing results after evaluation of the code block;
17025 Collection options specify the results. Choose one of the options;
17026 they are mutually exclusive.
17030 Default. Functional mode. Org gets the value by wrapping the code
17031 in a function definition in the language of the source block. That
17032 is why when using =:results value=, code should execute like
17033 a function and return a value. For languages like Python, an
17034 explicit ~return~ statement is mandatory when using =:results
17035 value=. Result is the value returned by the last statement in the
17038 When evaluating the code block in a session (see [[*Environment of
17039 a Code Block]]), Org passes the code to an interpreter running as an
17040 interactive Emacs inferior process. Org gets the value from the
17041 source code interpreter's last statement output. Org has to use
17042 language-specific methods to obtain the value. For example, from
17043 the variable ~_~ in Python and Ruby, and the value of ~.Last.value~
17048 Scripting mode. Org passes the code to an external process running
17049 the interpreter. Org returns the contents of the standard output
17050 stream as text results.
17052 When using a session, Org passes the code to the interpreter running
17053 as an interactive Emacs inferior process. Org concatenates any text
17054 output from the interpreter and returns the collection as a result.
17056 Note that this collection is not the same as that would be collected
17057 from stdout of a non-interactive interpreter running as an external
17058 process. Compare for example these two blocks:
17061 ,#+BEGIN_SRC python :results output
17072 In the above non-session mode, the "2" is not printed; so it does
17073 not appear in results.
17076 ,#+BEGIN_SRC python :results output :session
17088 In the above session, the interactive interpreter receives and
17089 prints "2". Results show that.
17096 Type tells what result types to expect from the execution of the code
17097 block. Choose one of the options; they are mutually exclusive. The
17098 default behavior is to automatically determine the result type.
17100 #+attr_texinfo: :sep ,
17101 - =table=, =vector= ::
17103 Interpret the results as an Org table. If the result is a single
17104 value, create a table with one row and one column. Usage example:
17105 =:results value table=.
17107 #+cindex: @samp{hlines}, header argument
17108 In-between each table row or below the table headings, sometimes
17109 results have horizontal lines, which are also known as "hlines".
17110 The =hlines= argument with the default =no= value strips such lines
17111 from the input table. For most code, this is desirable, or else
17112 those =hline= symbols raise unbound variable errors. A =yes=
17113 accepts such lines, as demonstrated in the following example.
17124 ,#+BEGIN_SRC python :var tab=many-cols :hlines no
17128 ,#+RESULTS: no-hline
17134 ,#+BEGIN_SRC python :var tab=many-cols :hlines yes
17148 Interpret the results as an Org list. If the result is a single
17149 value, create a list of one element.
17151 - =scalar=, =verbatim= ::
17153 Interpret literally and insert as quoted text. Do not create
17154 a table. Usage example: =:results value verbatim=.
17158 Interpret as a filename. Save the results of execution of the code
17159 block to that file, then insert a link to it. You can control both
17160 the filename and the description associated to the link.
17162 #+cindex: @samp{file}, header argument
17163 #+cindex: @samp{output-dir}, header argument
17164 Org first tries to generate the filename from the value of the
17165 =file= header argument and the directory specified using the
17166 =output-dir= header arguments. If =output-dir= is not specified,
17167 Org assumes it is the current directory.
17170 ,#+BEGIN_SRC asymptote :results value file :file circle.pdf :output-dir img/
17176 #+cindex: @samp{file-ext}, header argument
17177 If =file= is missing, Org generates the base name of the output
17178 file from the name of the code block, and its extension from the
17179 =file-ext= header argument. In that case, both the name and the
17180 extension are mandatory[fn:142].
17184 ,#+BEGIN_SRC asymptote :results value file :file-ext pdf
17190 #+cindex: @samp{file-desc}, header argument
17191 The =file-desc= header argument defines the description (see
17192 [[*Link Format]]) for the link. If =file-desc= has no value, Org
17193 uses the generated file name for both the "link" and
17194 "description" parts of the link.
17196 #+cindex: @samp{sep}, header argument
17197 By default, Org assumes that a table written to a file has
17198 TAB-delimited output. You can choose a different separator with
17199 the =sep= header argument.
17206 Format pertains to the type of the result returned by the code block.
17207 Choose one of the options; they are mutually exclusive. The default
17208 follows from the type specified above.
17210 #+attr_texinfo: :sep ,
17213 Result enclosed in a code block. Useful for parsing. Usage
17214 example: =:results value code=.
17218 Result wrapped in a =RESULTS= drawer. Useful for containing =raw=
17219 or =org= results for later scripting and automated processing.
17220 Usage example: =:results value drawer=.
17224 Results enclosed in a =BEGIN_EXPORT html= block. Usage example:
17225 =:results value html=.
17229 Results enclosed in a =BEGIN_EXPORT latex= block. Usage example:
17230 =:results value latex=.
17232 - =link=, =graphics= ::
17234 Result is a link to the file specified in =:file= header argument.
17235 However, unlike plain =:file=, nothing is written to the disk. The
17236 block is used for its side-effects only, as in the following
17240 ,#+begin_src shell :results link :file "download.tar.gz"
17241 wget -c "http://example.com/download.tar.gz"
17247 Results enclosed in a =BEGIN_SRC org= block. For comma-escape,
17248 either {{{kbd(TAB)}}} in the block, or export the file. Usage
17249 example: =:results value org=.
17253 Result converted to pretty-print source code. Enclosed in a code
17254 block. Languages supported: Emacs Lisp, Python, and Ruby. Usage
17255 example: =:results value pp=.
17259 Interpreted as raw Org mode. Inserted directly into the buffer.
17260 Aligned if it is a table. Usage example: =:results value raw=.
17262 #+cindex: @samp{wrap}, header argument
17263 The =wrap= header argument unconditionnally marks the results block by
17264 appending strings to =#+BEGIN_= and =#+END_=. If no string is
17265 specified, Org wraps the results in a =#+BEGIN_results=
17266 ... =#+END_results= block. It takes precedent over the =results=
17267 value listed above. E.g.,
17270 ,#+BEGIN_SRC emacs-lisp :results html :wrap EXPORT markdown
17271 "<blink>Welcome back to the 90's</blink>"
17275 ,#+BEGIN_EXPORT markdown
17276 <blink>Welcome back to the 90's</blink>
17285 Handling options after collecting the results.
17289 Do not insert results in the Org mode buffer, but echo them in the
17290 minibuffer. Usage example: =:results output silent=.
17294 Default. Insert results in the Org buffer. Remove previous
17295 results. Usage example: =:results output replace=.
17299 Append results to the Org buffer. Latest results are at the bottom.
17300 Does not remove previous results. Usage example: =:results output
17305 Prepend results to the Org buffer. Latest results are at the top.
17306 Does not remove previous results. Usage example: =:results output
17309 *** Post-processing
17314 #+cindex: @samp{post}, header argument
17315 #+cindex: @samp{*this*}, in @samp{post} header argument
17316 The =post= header argument is for post-processing results from block
17317 evaluation. When =post= has any value, Org binds the results to
17318 ~*this*~ variable for easy passing to =var= header argument
17319 specifications (see [[*Environment of a Code Block]]). That makes results
17320 available to other code blocks, or even for direct Emacs Lisp code
17323 The following two examples illustrate =post= header argument in
17324 action. The first one shows how to attach an =ATTR_LATEX= keyword
17329 ,#+BEGIN_SRC sh :var data="" :var width="\\textwidth" :results output
17330 echo "#+ATTR_LATEX: :width $width"
17334 ,#+HEADER: :file /tmp/it.png
17335 ,#+BEGIN_SRC dot :post attr_wrap(width="5cm", data=*this*) :results drawer
17345 ,#+ATTR_LATEX :width 5cm
17346 [[file:/tmp/it.png]]
17350 The second example shows use of =colnames= header argument in =post=
17351 to pass data between code blocks.
17355 ,#+BEGIN_SRC emacs-lisp :var tbl="" fmt="%.3f"
17356 (mapcar (lambda (row)
17357 (mapcar (lambda (cell)
17365 ,#+BEGIN_SRC R :colnames yes :post round-tbl[:colnames yes](*this*)
17367 data.frame(foo=rnorm(1))
17376 ** Exporting Code Blocks
17378 :DESCRIPTION: Export contents and/or results.
17380 #+cindex: code block, exporting
17381 #+cindex: source code, exporting
17383 It is possible to export the /code/ of code blocks, the /results/ of
17384 code block evaluation, /both/ the code and the results of code block
17385 evaluation, or /none/. Org defaults to exporting /code/ for most
17386 languages. For some languages, such as ditaa, Org defaults to
17387 /results/. To export just the body of code blocks, see [[*Literal
17388 Examples]]. To selectively export sub-trees of an Org document, see
17391 #+cindex: @samp{exports}, header argument
17392 The =exports= header argument is to specify if that part of the Org
17393 file is exported to, say, HTML or LaTeX formats.
17397 The default. The body of code is included into the exported file.
17398 Example: =:exports code=.
17402 The results of evaluation of the code is included in the exported
17403 file. Example: =:exports results=.
17407 Both the code and results of evaluation are included in the exported
17408 file. Example: =:exports both=.
17412 Neither the code nor the results of evaluation is included in the
17413 exported file. Whether the code is evaluated at all depends on
17414 other options. Example: =:exports none=.
17416 #+vindex: org-export-use-babel
17417 To stop Org from evaluating code blocks to speed exports, use the
17418 header argument =:eval never-export= (see [[*Evaluating Code Blocks]]).
17419 To stop Org from evaluating code blocks for greater security, set the
17420 ~org-export-use-babel~ variable to ~nil~, but understand that header
17421 arguments will have no effect.
17423 Turning off evaluation comes in handy when batch processing. For
17424 example, markup languages for wikis, which have a high risk of
17425 untrusted code. Stopping code block evaluation also stops evaluation
17426 of all header arguments of the code block. This may not be desirable
17427 in some circumstances. So during export, to allow evaluation of just
17428 the header arguments but not any code evaluation in the source block,
17429 set =:eval never-export= (see [[*Evaluating Code Blocks]]).
17431 Org never evaluates code blocks in commented sub-trees when exporting
17432 (see [[*Comment Lines]]). On the other hand, Org does evaluate code
17433 blocks in sub-trees excluded from export (see [[*Export Settings]]).
17435 ** Extracting Source Code
17437 :DESCRIPTION: Create pure source code files.
17440 #+cindex: source code, extracting
17441 #+cindex: code block, extracting source code
17443 Extracting source code from code blocks is a basic task in literate
17444 programming. Org has features to make this easy. In literate
17445 programming parlance, documents on creation are /woven/ with code and
17446 documentation, and on export, the code is tangled for execution by
17447 a computer. Org facilitates weaving and tangling for producing,
17448 maintaining, sharing, and exporting literate programming documents.
17449 Org provides extensive customization options for extracting source
17452 When Org tangles code blocks, it expands, merges, and transforms them.
17453 Then Org recomposes them into one or more separate files, as
17454 configured through the options. During this tangling process, Org
17455 expands variables in the source code, and resolves any Noweb style
17456 references (see [[*Noweb Reference Syntax]]).
17458 *** Header arguments
17463 #+cindex: @samp{tangle}, header argument
17464 The =tangle= header argument specifies if the code block is exported
17469 Export the code block to source file. The file name for the source
17470 file is derived from the name of the Org file, and the file
17471 extension is derived from the source code language identifier.
17472 Example: =:tangle yes=.
17476 The default. Do not extract the code in a source code file.
17477 Example: =:tangle no=.
17479 - {{{var(FILENAME)}}} ::
17481 Export the code block to source file whose file name is derived from
17482 any string passed to the =tangle= header argument. Org derives the
17483 file name as being relative to the directory of the Org file's
17484 location. Example: =:tangle FILENAME=.
17486 #+cindex: @samp{mkdirp}, header argument
17487 The =mkdirp= header argument creates parent directories for =dir=
17488 header argument specified path and tangled files if the directory does
17489 not exist. =yes= enables directory creation and =no= inhibits
17490 directory creation.
17492 #+cindex: @samp{comments}, header argument
17493 The =comments= header argument controls inserting comments into
17494 tangled files. These are above and beyond whatever comments may
17495 already exist in the code block.
17499 The default. Do not insert any extra comments during tangling.
17503 Wrap the code block in comments. Include links pointing back to the
17504 place in the Org file from where the code was tangled.
17508 Kept for backward compatibility; same as =link=.
17512 Nearest headline text from Org file is inserted as comment. The
17513 exact text that is inserted is picked from the leading context of
17518 Includes both =link= and =org= options.
17522 Includes =link= option, expands Noweb references (see [[*Noweb
17523 Reference Syntax]]), and wraps them in link comments inside the body
17526 #+cindex: @samp{padline}, header argument
17527 The =padline= header argument controls insertion of newlines to pad
17528 source code in the tangled file.
17532 Default. Insert a newline before and after each code block in the
17537 Do not insert newlines to pad the tangled code blocks.
17539 #+cindex: @samp{shebang}, header argument
17540 The =shebang= header argument can turn results into executable script
17541 files. By setting it to a string value---for example, =:shebang
17542 "#!/bin/bash"=---Org inserts that string as the first line of the
17543 tangled file that the code block is extracted to. Org then turns on
17544 the tangled file's executable permission.
17546 #+cindex: @samp{tangle-mode}, header argument
17547 The =tangle-mode= header argument specifies what permissions to set
17548 for tangled files by ~set-file-modes~. For example, to make
17549 a read-only tangled file, use =:tangle-mode (identity #o444)=. To
17550 make it executable, use =:tangle-mode (identity #o755)=. It also
17551 overrides executable permission granted by =shebang=. When multiple
17552 source code blocks tangle to a single file with different and
17553 conflicting =tangle-mode= header arguments, Org's behavior is
17556 #+cindex: @samp{no-expand}, header argument
17557 By default Org expands code blocks during tangling. The =no-expand=
17558 header argument turns off such expansions. Note that one side-effect
17559 of expansion by ~org-babel-expand-src-block~ also assigns values (see
17560 [[*Environment of a Code Block]]) to variables. Expansions also replace
17561 Noweb references with their targets (see [[*Noweb Reference Syntax]]).
17562 Some of these expansions may cause premature assignment, hence this
17563 option. This option makes a difference only for tangling. It has no
17564 effect when exporting since code blocks for execution have to be
17572 - ~org-babel-tangle~ ::
17574 #+findex: org-babel-tangle
17575 #+kindex: C-c C-v t
17576 Tangle the current file. Bound to {{{kbd(C-c C-v t)}}}.
17578 With prefix argument only tangle the current code block.
17580 - ~org-babel-tangle-file~ ::
17582 #+findex: org-babel-tangle-file
17583 #+kindex: C-c C-v f
17584 Choose a file to tangle. Bound to {{{kbd(C-c C-v f)}}}.
17591 - ~org-babel-post-tangle-hook~ ::
17593 #+vindex: org-babel-post-tangle-hook
17594 This hook is run from within code files tangled by
17595 ~org-babel-tangle~, making it suitable for post-processing,
17596 compilation, and evaluation of code in the tangled files.
17598 *** Jumping between code and Org
17603 #+findex: org-babel-tangle-jump-to-org
17604 Debuggers normally link errors and messages back to the source code.
17605 But for tangled files, we want to link back to the Org file, not to
17606 the tangled source file. To make this extra jump, Org uses
17607 ~org-babel-tangle-jump-to-org~ function with two additional source
17608 code block header arguments:
17610 1. Set =padline= to true---this is the default setting.
17611 2. Set =comments= to =link=, which makes Org insert links to the Org
17616 :DESCRIPTION: List of supported code block languages.
17618 #+cindex: babel, languages
17619 #+cindex: source code, languages
17620 #+cindex: code block, languages
17622 Code blocks in the following languages are supported.
17624 #+attr_texinfo: :columns 0.20 0.35 0.20 0.20
17625 | Language | Identifier | Language | Identifier |
17626 |------------+---------------+----------------+--------------|
17627 | Asymptote | =asymptote= | Lisp | =lisp= |
17628 | Awk | =awk= | Lua | =lua= |
17629 | C | =C= | MATLAB | =matlab= |
17630 | C++ | =C++=[fn:143] | Mscgen | =mscgen= |
17631 | Clojure | =clojure= | Objective Caml | =ocaml= |
17632 | CSS | =css= | Octave | =octave= |
17633 | D | =D=[fn:144] | Org mode | =org= |
17634 | ditaa | =ditaa= | Oz | =oz= |
17635 | Emacs Calc | =calc= | Perl | =perl= |
17636 | Emacs Lisp | =emacs-lisp= | Plantuml | =plantuml= |
17637 | Eshell | =eshell= | Processing.js | =processing= |
17638 | Fortran | =fortran= | Python | =python= |
17639 | Gnuplot | =gnuplot= | R | =R= |
17640 | GNU Screen | =screen= | Ruby | =ruby= |
17641 | Graphviz | =dot= | Sass | =sass= |
17642 | Haskell | =haskell= | Scheme | =scheme= |
17643 | Java | =java= | Sed | =sed= |
17644 | Javascript | =js= | shell | =sh= |
17645 | LaTeX | =latex= | SQL | =sql= |
17646 | Ledger | =ledger= | SQLite | =sqlite= |
17647 | Lilypond | =lilypond= | Vala | =vala= |
17649 Additional documentation for some languages is at
17650 https://orgmode.org/worg/org-contrib/babel/languages.html.
17652 #+vindex: org-babel-load-languages
17653 By default, only Emacs Lisp is enabled for evaluation. To enable or
17654 disable other languages, customize the ~org-babel-load-languages~
17655 variable either through the Emacs customization interface, or by
17656 adding code to the init file as shown next.
17658 In this example, evaluation is disabled for Emacs Lisp, and enabled
17661 #+begin_src emacs-lisp
17662 (org-babel-do-load-languages
17663 'org-babel-load-languages
17664 '((emacs-lisp . nil)
17668 Note that this is not the only way to enable a language. Org also
17669 enables languages when loaded with ~require~ statement. For example,
17670 the following enables execution of Clojure code blocks:
17672 #+begin_src emacs-lisp
17673 (require 'ob-clojure)
17676 ** Editing Source Code
17678 :DESCRIPTION: Language major-mode editing.
17680 #+cindex: code block, editing
17681 #+cindex: source code, editing
17684 Use {{{kbd(C-c ')}}} to edit the current code block. It opens a new
17685 major-mode edit buffer containing the body of the source code block,
17686 ready for any edits. Use {{{kbd(C-c ')}}} again to close the buffer
17687 and return to the Org buffer.
17690 #+vindex: org-edit-src-auto-save-idle-delay
17691 #+cindex: auto-save, in code block editing
17692 {{{kbd(C-x C-s)}}} saves the buffer and updates the contents of the
17693 Org buffer. Set ~org-edit-src-auto-save-idle-delay~ to save the base
17694 buffer after a certain idle delay time. Set
17695 ~org-edit-src-turn-on-auto-save~ to auto-save this buffer into
17696 a separate file using Auto-save mode.
17698 While editing the source code in the major mode, the Org Src minor
17699 mode remains active. It provides these customization variables as
17700 described below. For even more variables, look in the customization
17701 group ~org-edit-structure~.
17703 - ~org-src-lang-modes~ ::
17705 #+vindex: org-src-lang-modes
17706 If an Emacs major-mode named ~<LANG>-mode~ exists, where
17707 {{{var(<LANG>)}}} is the language identifier from code block's
17708 header line, then the edit buffer uses that major mode. Use this
17709 variable to arbitrarily map language identifiers to major modes.
17711 - ~org-src-window-setup~ ::
17713 #+vindex: org-src-window-setup
17714 For specifying Emacs window arrangement when the new edit buffer is
17717 - ~org-src-preserve-indentation~ ::
17719 #+cindex: indentation, in code blocks
17720 #+vindex: org-src-preserve-indentation
17721 Default is ~nil~. Source code is indented. This indentation
17722 applies during export or tangling, and depending on the context, may
17723 alter leading spaces and tabs. When non-~nil~, source code is
17724 aligned with the leftmost column. No lines are modified during
17725 export or tangling, which is very useful for white-space sensitive
17726 languages, such as Python.
17728 - ~org-src-ask-before-returning-to-edit-buffer~ ::
17730 #+vindex: org-src-ask-before-returning-to-edit-buffer
17731 When ~nil~, Org returns to the edit buffer without further prompts.
17732 The default prompts for a confirmation.
17734 #+vindex: org-src-fontify-natively
17735 #+vindex: org-src-block-faces
17736 Set ~org-src-fontify-natively~ to non-~nil~ to turn on native code
17737 fontification in the /Org/ buffer. Fontification of code blocks can
17738 give visual separation of text and code on the display page. To
17739 further customize the appearance of ~org-block~ for specific
17740 languages, customize ~org-src-block-faces~. The following example
17741 shades the background of regular blocks, and colors source blocks only
17742 for Python and Emacs Lisp languages.
17744 #+begin_src emacs-lisp
17746 (set-face-attribute 'org-block nil :background
17748 (face-attribute 'default :background) 3))
17750 (setq org-src-block-faces '(("emacs-lisp" (:background "#EEE2FF"))
17751 ("python" (:background "#E5FFB8"))))
17754 ** Noweb Reference Syntax
17756 :DESCRIPTION: Literate programming in Org mode.
17758 #+cindex: code block, Noweb reference
17759 #+cindex: syntax, Noweb
17760 #+cindex: source code, Noweb reference
17762 Org supports named blocks in Noweb[fn:145] style syntax:
17764 : <<CODE-BLOCK-ID>>
17766 Org can replace the construct with the source code, or the results of
17767 evaluation, of the code block identified as {{{var(CODE-BLOCK-ID)}}}.
17769 #+cindex: @samp{noweb}, header argument
17770 The =noweb= header argument controls expansion of Noweb syntax
17771 references. Expansions occur when source code blocks are evaluated,
17772 tangled, or exported.
17776 Default. No expansion of Noweb syntax references in the body of the
17777 code when evaluating, tangling, or exporting.
17781 Expansion of Noweb syntax references in the body of the code block
17782 when evaluating, tangling, or exporting.
17786 Expansion of Noweb syntax references in the body of the code block
17787 when tangling. No expansion when evaluating or exporting.
17791 Expansion of Noweb syntax references in the body of the code block
17792 when evaluating or tangling. No expansion when exporting.
17794 - =strip-export= ::
17796 Expansion of Noweb syntax references in the body of the code block
17797 when expanding prior to evaluating or tangling. Removes Noweb
17798 syntax references when exporting.
17802 Expansion of Noweb syntax references in the body of the code block
17803 only before evaluating.
17805 In the following example,
17808 ,#+NAME: initialization
17809 ,#+BEGIN_SRC emacs-lisp
17810 (setq sentence "Never a foot too far, even.")
17813 ,#+BEGIN_SRC emacs-lisp :noweb yes
17819 #+texinfo: @noindent
17820 the second code block is expanded as
17823 ,#+BEGIN_SRC emacs-lisp :noweb yes
17824 (setq sentence "Never a foot too far, even.")
17829 Noweb insertions honor prefix characters that appear before the Noweb
17830 syntax reference. This behavior is illustrated in the following
17831 example. Because the =<<example>>= Noweb reference appears behind the
17832 SQL comment syntax, each line of the expanded Noweb reference is
17839 multi-line body of example
17843 #+texinfo: @noindent
17847 ,#+BEGIN_SRC sql :noweb yes
17852 #+texinfo: @noindent
17856 ,#+BEGIN_SRC sql :noweb yes
17858 ---multi-line body of example
17862 Since this change does not affect Noweb replacement text without
17863 newlines in them, inline Noweb references are acceptable.
17865 This feature can also be used for management of indentation in
17866 exported code snippets. With:
17870 ,#+BEGIN_SRC python :exports none
17871 print('do things when true')
17875 ,#+begin_src python :exports none
17876 print('do things when false')
17880 #+texinfo: @noindent
17884 ,#+begin_src python :noweb yes :results output
17892 #+texinfo: @noindent
17897 print('do things when true')
17899 print('do things when false')
17902 #+cindex: @samp{noweb-ref}, header argument
17903 When expanding Noweb style references, Org concatenates code blocks by
17904 matching the reference name to either the code block name or, if none
17905 is found, to the =noweb-ref= header argument.
17907 For simple concatenation, set this =noweb-ref= header argument at the
17908 sub-tree or file level. In the example Org file shown next, the body
17909 of the source code in each block is extracted for concatenation to
17910 a pure code file when tangled.
17913 ,#+BEGIN_SRC sh :tangle yes :noweb yes :shebang #!/bin/sh
17916 ,* the mount point of the fullest disk
17918 :header-args: :noweb-ref fullest-disk
17921 ,** query all mounted disks
17926 ,** strip the header row
17931 ,** output mount point of fullest disk
17933 |awk '{if (u < +$5) {u = +$5; m = $6}} END {print m}'
17937 #+cindex: @samp{noweb-sep}, header argument
17938 By default a newline separates each noweb reference concatenation. To
17939 change this newline separator, edit the =noweb-sep= header argument.
17941 Eventually, Org can include the results of a code block rather than
17942 its body. To that effect, append parentheses, possibly including
17943 arguments, to the code block name, as shown below.
17945 : <<code-block-name(optional arguments)>>
17947 Note that when using the above approach to a code block's results, the
17948 code block name set by =NAME= keyword is required; the reference set
17949 by =noweb-ref= does not work in that case.
17951 Here is an example that demonstrates how the exported content changes
17952 when Noweb style references are used with parentheses versus without.
17957 ,#+BEGIN_SRC python :var num=0 :results output :exports none
17962 #+texinfo: @noindent
17966 ,#+BEGIN_SRC text :noweb yes
17971 #+texinfo: @noindent
17976 Below, a similar Noweb style reference is used, but with parentheses,
17977 while setting a variable =num= to 10:
17980 ,#+BEGIN_SRC text :noweb yes
17981 <<some-code(num=10)>>
17985 #+texinfo: @noindent
17986 Note that now the expansion contains the results of the code block
17987 =some-code=, not the code block itself:
17991 ** Library of Babel
17993 :DESCRIPTION: Use and contribute to a library of useful code blocks.
17995 #+cindex: babel, library of
17996 #+cindex: source code, library
17997 #+cindex: code block, library
17999 The "Library of Babel" is a collection of code blocks. Like
18000 a function library, these code blocks can be called from other Org
18001 files. A collection of useful code blocks is available on [[https://orgmode.org/worg/library-of-babel.html][Worg]]. For
18002 remote code block evaluation syntax, see [[*Evaluating Code Blocks]].
18004 #+kindex: C-c C-v i
18005 #+findex: org-babel-lob-ingest
18006 For any user to add code to the library, first save the code in
18007 regular code blocks of an Org file, and then load the Org file with
18008 ~org-babel-lob-ingest~, which is bound to {{{kbd(C-c C-v i)}}}.
18010 ** Key bindings and Useful Functions
18012 :DESCRIPTION: Work quickly with code blocks.
18014 #+cindex: code block, key bindings
18016 Many common Org mode key sequences are re-bound depending on
18019 Active key bindings in code blocks:
18022 #+findex: org-babel-execute-src-block
18024 #+findex: org-babel-open-src-block-result
18026 #+findex: org-babel-load-in-session
18028 #+findex: org-babel-pop-to-session
18029 #+attr_texinfo: :columns 0.2 0.55
18030 | Key binding | Function |
18031 |--------------------+-----------------------------------|
18032 | {{{kbd(C-c C-c)}}} | ~org-babel-execute-src-block~ |
18033 | {{{kbd(C-c C-o)}}} | ~org-babel-open-src-block-result~ |
18034 | {{{kbd(M-UP)}}} | ~org-babel-load-in-session~ |
18035 | {{{kbd(M-DOWN)}}} | ~org-babel-pop-to-session~ |
18037 Active key bindings in Org mode buffer:
18039 #+kindex: C-c C-v p
18040 #+kindex: C-c C-v C-p
18041 #+kindex: C-c C-v n
18042 #+kindex: C-c C-v C-n
18043 #+kindex: C-c C-v e
18044 #+kindex: C-c C-v C-e
18045 #+kindex: C-c C-v o
18046 #+kindex: C-c C-v C-o
18047 #+kindex: C-c C-v v
18048 #+kindex: C-c C-v C-v
18049 #+kindex: C-c C-v u
18050 #+kindex: C-c C-v C-u
18051 #+kindex: C-c C-v g
18052 #+kindex: C-c C-v C-g
18053 #+kindex: C-c C-v r
18054 #+kindex: C-c C-v C-r
18055 #+kindex: C-c C-v b
18056 #+kindex: C-c C-v C-b
18057 #+kindex: C-c C-v s
18058 #+kindex: C-c C-v C-s
18059 #+kindex: C-c C-v d
18060 #+kindex: C-c C-v C-d
18061 #+kindex: C-c C-v t
18062 #+kindex: C-c C-v C-t
18063 #+kindex: C-c C-v f
18064 #+kindex: C-c C-v C-f
18065 #+kindex: C-c C-v c
18066 #+kindex: C-c C-v C-c
18067 #+kindex: C-c C-v j
18068 #+kindex: C-c C-v C-j
18069 #+kindex: C-c C-v l
18070 #+kindex: C-c C-v C-l
18071 #+kindex: C-c C-v i
18072 #+kindex: C-c C-v C-i
18073 #+kindex: C-c C-v I
18074 #+kindex: C-c C-v C-I
18075 #+kindex: C-c C-v z
18076 #+kindex: C-c C-v C-z
18077 #+kindex: C-c C-v a
18078 #+kindex: C-c C-v C-a
18079 #+kindex: C-c C-v h
18080 #+kindex: C-c C-v C-h
18081 #+kindex: C-c C-v x
18082 #+kindex: C-c C-v C-x
18083 #+findex: org-babel-previous-src-block
18084 #+findex: org-babel-next-src-block
18085 #+findex: org-babel-execute-maybe
18086 #+findex: org-babel-open-src-block-result
18087 #+findex: org-babel-expand-src-block
18088 #+findex: org-babel-goto-src-block-head
18089 #+findex: org-babel-goto-named-src-block
18090 #+findex: org-babel-goto-named-result
18091 #+findex: org-babel-execute-buffer
18092 #+findex: org-babel-execute-subtree
18093 #+findex: org-babel-demarcate-block
18094 #+findex: org-babel-tangle
18095 #+findex: org-babel-tangle-file
18096 #+findex: org-babel-check-src-block
18097 #+findex: org-babel-insert-header-arg
18098 #+findex: org-babel-load-in-session
18099 #+findex: org-babel-lob-ingest
18100 #+findex: org-babel-view-src-block-info
18101 #+findex: org-babel-switch-to-session-with-code
18102 #+findex: org-babel-sha1-hash
18103 #+findex: org-babel-describe-bindings
18104 #+findex: org-babel-do-key-sequence-in-edit-buffer
18105 #+attr_texinfo: :columns 0.45 0.55
18106 | Key binding | Function |
18107 |------------------------------------------------+--------------------------------------------|
18108 | {{{kbd(C-c C-v p)}}} or {{{kbd(C-c C-v C-p)}}} | ~org-babel-previous-src-block~ |
18109 | {{{kbd(C-c C-v n)}}} or {{{kbd(C-c C-v C-n)}}} | ~org-babel-next-src-block~ |
18110 | {{{kbd(C-c C-v e)}}} or {{{kbd(C-c C-v C-e)}}} | ~org-babel-execute-maybe~ |
18111 | {{{kbd(C-c C-v o)}}} or {{{kbd(C-c C-v C-o)}}} | ~org-babel-open-src-block-result~ |
18112 | {{{kbd(C-c C-v v)}}} or {{{kbd(C-c C-v C-v)}}} | ~org-babel-expand-src-block~ |
18113 | {{{kbd(C-c C-v u)}}} or {{{kbd(C-c C-v C-u)}}} | ~org-babel-goto-src-block-head~ |
18114 | {{{kbd(C-c C-v g)}}} or {{{kbd(C-c C-v C-g)}}} | ~org-babel-goto-named-src-block~ |
18115 | {{{kbd(C-c C-v r)}}} or {{{kbd(C-c C-v C-r)}}} | ~org-babel-goto-named-result~ |
18116 | {{{kbd(C-c C-v b)}}} or {{{kbd(C-c C-v C-b)}}} | ~org-babel-execute-buffer~ |
18117 | {{{kbd(C-c C-v s)}}} or {{{kbd(C-c C-v C-s)}}} | ~org-babel-execute-subtree~ |
18118 | {{{kbd(C-c C-v d)}}} or {{{kbd(C-c C-v C-d)}}} | ~org-babel-demarcate-block~ |
18119 | {{{kbd(C-c C-v t)}}} or {{{kbd(C-c C-v C-t)}}} | ~org-babel-tangle~ |
18120 | {{{kbd(C-c C-v f)}}} or {{{kbd(C-c C-v C-f)}}} | ~org-babel-tangle-file~ |
18121 | {{{kbd(C-c C-v c)}}} or {{{kbd(C-c C-v C-c)}}} | ~org-babel-check-src-block~ |
18122 | {{{kbd(C-c C-v j)}}} or {{{kbd(C-c C-v C-j)}}} | ~org-babel-insert-header-arg~ |
18123 | {{{kbd(C-c C-v l)}}} or {{{kbd(C-c C-v C-l)}}} | ~org-babel-load-in-session~ |
18124 | {{{kbd(C-c C-v i)}}} or {{{kbd(C-c C-v C-i)}}} | ~org-babel-lob-ingest~ |
18125 | {{{kbd(C-c C-v I)}}} or {{{kbd(C-c C-v C-I)}}} | ~org-babel-view-src-block-info~ |
18126 | {{{kbd(C-c C-v z)}}} or {{{kbd(C-c C-v C-z)}}} | ~org-babel-switch-to-session-with-code~ |
18127 | {{{kbd(C-c C-v a)}}} or {{{kbd(C-c C-v C-a)}}} | ~org-babel-sha1-hash~ |
18128 | {{{kbd(C-c C-v h)}}} or {{{kbd(C-c C-v C-h)}}} | ~org-babel-describe-bindings~ |
18129 | {{{kbd(C-c C-v x)}}} or {{{kbd(C-c C-v C-x)}}} | ~org-babel-do-key-sequence-in-edit-buffer~ |
18133 :DESCRIPTION: Call functions from the command line.
18135 #+cindex: code block, batch execution
18136 #+cindex: source code, batch execution
18138 Org mode features, including working with source code facilities can
18139 be invoked from the command line. This enables building shell scripts
18140 for batch processing, running automated system tasks, and expanding
18141 Org mode's usefulness.
18143 The sample script shows batch processing of multiple files using
18144 ~org-babel-tangle~.
18148 # Tangle files with Org mode
18150 emacs -Q --batch --eval "
18152 (require 'ob-tangle)
18153 (dolist (file command-line-args-left)
18154 (with-current-buffer (find-file-noselect file)
18155 (org-babel-tangle))))
18161 :DESCRIPTION: All the rest which did not fit elsewhere.
18166 :DESCRIPTION: @kbd{M-@key{TAB}} guesses completions.
18168 #+cindex: completion, of @TeX{} symbols
18169 #+cindex: completion, of TODO keywords
18170 #+cindex: completion, of dictionary words
18171 #+cindex: completion, of option keywords
18172 #+cindex: completion, of tags
18173 #+cindex: completion, of property keys
18174 #+cindex: completion, of link abbreviations
18175 #+cindex: @TeX{} symbol completion
18176 #+cindex: TODO keywords completion
18177 #+cindex: dictionary word completion
18178 #+cindex: option keyword completion
18179 #+cindex: tag completion
18180 #+cindex: link abbreviations, completion of
18182 Org has in-buffer completions. Unlike minibuffer completions, which
18183 are useful for quick command interactions, Org's in-buffer completions
18184 are more suitable for content creation in Org documents. Type one or
18185 more letters and invoke the hot key to complete the text in-place.
18186 Depending on the context and the keys, Org offers different types of
18187 completions. No minibuffer is involved. Such mode-specific hot keys
18188 have become an integral part of Emacs and Org provides several
18191 - {{{kbd(M-TAB)}}} ::
18194 Complete word at point.
18196 - At the beginning of a headline, complete TODO keywords.
18198 - After =\=, complete TeX symbols supported by the exporter.
18200 - After =*=, complete headlines in the current buffer so that they
18201 can be used in search links like:
18203 : [[*find this headline]]
18205 - After =:= in a headline, complete tags. Org deduces the list of
18206 tags from the =TAGS= in-buffer option (see [[*Setting Tags]]), the
18207 variable ~org-tag-alist~, or from all tags used in the current
18210 - After =:= and not in a headline, complete property keys. The list
18211 of keys is constructed dynamically from all keys used in the
18214 - After =[=, complete link abbreviations (see [[*Link Abbreviations]]).
18216 - After =#+=, complete the special keywords like =TYP_TODO= or
18217 file-specific =OPTIONS=. After option keyword is complete,
18218 pressing {{{kbd(M-TAB)}}} again inserts example settings for this
18221 - After =STARTUP= keyword, complete startup items.
18223 - When point is anywhere else, complete dictionary words using
18226 ** Structure Templates
18228 :DESCRIPTION: Quick insertion of structural elements.
18230 #+cindex: template insertion
18231 #+cindex: insertion, of templates
18233 With just a few keystrokes, it is possible to insert empty structural
18234 blocks, such as =#+BEGIN_SRC= ... =#+END_SRC=, or to wrap existing
18235 text in such a block.
18237 - {{{kbd(C-c C-\,)}}} (~org-insert-structure-template~) ::
18239 #+findex: org-insert-structure-template
18241 Prompt for a type of block structure, and insert the block at point.
18242 If the region is active, it is wrapped in the block. First prompts
18243 the user for keys, which are used to look up a structure type from
18244 the variable below. If the key is {{{kbd(TAB)}}}, {{{kbd(RET)}}},
18245 or {{{kbd(SPC)}}}, the user is prompted to enter a block type.
18247 #+vindex: org-structure-template-alist
18248 Available structure types are defined in
18249 ~org-structure-template-alist~, see the docstring for adding or
18253 #+cindex: template expansion
18254 #+cindex: insertion, of templates
18255 #+vindex: org-tempo-keywords-alist
18256 Org Tempo expands snippets to structures defined in
18257 ~org-structure-template-alist~ and ~org-tempo-keywords-alist~. For
18258 example, {{{kbd(< s TAB)}}} creates a code block. Enable it by
18259 customizing ~org-modules~ or add =(require 'org-tempo)= to your Emacs
18262 #+attr_texinfo: :columns 0.1 0.9
18263 | {{{kbd(a)}}} | =#+BEGIN_EXPORT ascii= ... =#+END_EXPORT= |
18264 | {{{kbd(c)}}} | =#+BEGIN_CENTER= ... =#+END_CENTER= |
18265 | {{{kbd(C)}}} | =#+BEGIN_COMMENT= ... =#+END_COMMENT= |
18266 | {{{kbd(e)}}} | =#+BEGIN_EXAMPLE= ... =#+END_EXAMPLE= |
18267 | {{{kbd(E)}}} | =#+BEGIN_EXPORT= ... =#+END_EXPORT= |
18268 | {{{kbd(h)}}} | =#+BEGIN_EXPORT html= ... =#+END_EXPORT= |
18269 | {{{kbd(l)}}} | =#+BEGIN_EXPORT latex= ... =#+END_EXPORT= |
18270 | {{{kbd(q)}}} | =#+BEGIN_QUOTE= ... =#+END_QUOTE= |
18271 | {{{kbd(s)}}} | =#+BEGIN_SRC= ... =#+END_SRC= |
18272 | {{{kbd(v)}}} | =#+BEGIN_VERSE= ... =#+END_VERSE= |
18274 ** Escape Character
18276 #+cindex: escape character
18277 #+cindex: zero width space
18278 You may sometimes want to write text that looks like Org syntax, but
18279 should really read as plain text. Org may use a specific escape
18280 character in some situations, e.g., a backslash in macros (see [[*Macro
18281 Replacement]]). In the general case, however, we suggest to use the
18282 zero width space. You can get it with one of the following:
18284 : C-x 8 <RET> zero width space <RET>
18285 : C-x 8 <RET> 200B <RET>
18287 For example, in order to write =[[1,2]]= as-is in your document, you can
18288 write this, where =X= denotes the zero width space character:
18294 :DESCRIPTION: Electric commands at the beginning of a headline.
18296 #+cindex: speed keys
18298 Single keystrokes can execute custom commands in an Org file when
18299 point is on a headline. Without the extra burden of a meta or
18300 modifier key, Speed Keys can speed navigation or execute custom
18301 commands. Besides faster navigation, Speed Keys may come in handy on
18302 small mobile devices that do not have full keyboards. Speed Keys may
18303 also work on TTY devices known for their problems when entering Emacs
18306 #+vindex: org-use-speed-commands
18307 By default, Org has Speed Keys disabled. To activate Speed Keys, set
18308 the variable ~org-use-speed-commands~ to a non-~nil~ value. To
18309 trigger a Speed Key, point must be at the beginning of an Org
18310 headline, before any of the stars.
18312 #+vindex: org-speed-commands-user
18313 #+findex: org-speed-command-help
18314 Org comes with a pre-defined list of Speed Keys. To add or modify
18315 Speed Keys, customize the variable, ~org-speed-commands-user~. For
18316 more details, see the variable's docstring. With Speed Keys
18317 activated, {{{kbd(M-x org-speed-command-help)}}}, or {{{kbd(?)}}} when
18318 point is at the beginning of an Org headline, shows currently active
18319 Speed Keys, including the user-defined ones.
18321 ** Code Evaluation and Security Issues
18323 :DESCRIPTION: Org files evaluate in-line code.
18324 :ALT_TITLE: Code Evaluation Security
18327 Unlike plain text, running code comes with risk. Each source code
18328 block, in terms of risk, is equivalent to an executable file. Org
18329 therefore puts a few confirmation prompts by default. This is to
18330 alert the casual user from accidentally running untrusted code.
18332 For users who do not run code blocks or write code regularly, Org's
18333 default settings should suffice. However, some users may want to
18334 tweak the prompts for fewer interruptions. To weigh the risks of
18335 automatic execution of code blocks, here are some details about code
18338 Org evaluates code in the following circumstances:
18340 - /Source code blocks/ ::
18342 Org evaluates source code blocks in an Org file during export. Org
18343 also evaluates a source code block with the {{{kbd(C-c C-c)}}} key
18344 chord. Users exporting or running code blocks must load files only
18345 from trusted sources. Be wary of customizing variables that remove
18346 or alter default security measures.
18348 #+attr_texinfo: :options org-confirm-babel-evaluate
18350 When ~t~, Org prompts the user for confirmation before executing
18351 each code block. When ~nil~, Org executes code blocks without
18352 prompting the user for confirmation. When this option is set to
18353 a custom function, Org invokes the function with these two
18354 arguments: the source code language and the body of the code block.
18355 The custom function must return either a ~t~ or ~nil~, which
18356 determines if the user is prompted. Each source code language can
18357 be handled separately through this function argument.
18360 For example, here is how to execute ditaa code blocks without
18363 #+begin_src emacs-lisp
18364 (defun my-org-confirm-babel-evaluate (lang body)
18365 (not (string= lang "ditaa"))) ;don't ask for ditaa
18366 (setq org-confirm-babel-evaluate #'my-org-confirm-babel-evaluate)
18369 - /Following =shell= and =elisp= links/ ::
18371 Org has two link types that can directly evaluate code (see
18372 [[*External Links]]). Because such code is not visible, these links
18373 have a potential risk. Org therefore prompts the user when it
18374 encounters such links. The customization variables are:
18376 #+attr_texinfo: :options org-confirm-shell-link-function
18378 Function that prompts the user before executing a shell link.
18381 #+attr_texinfo: :options org-confirm-elisp-link-function
18383 Function that prompts the user before executing an Emacs Lisp link.
18386 - /Formulas in tables/ ::
18388 Formulas in tables (see [[*The Spreadsheet]]) are code that is evaluated
18389 either by the Calc interpreter, or by the Emacs Lisp interpreter.
18393 :DESCRIPTION: Adapting Org to your taste.
18395 #+cindex: customization
18396 #+cindex: options, for customization
18397 #+cindex: variables, for customization
18399 Org has more than 500 variables for customization. They can be
18400 accessed through the usual {{{kbd(M-x org-customize)}}} command. Or
18401 through the Org menu: Org \rarr Customization \rarr Browse Org Group.
18403 Org also has per-file settings for some variables (see [[*Summary of
18404 In-Buffer Settings]]).
18406 ** Summary of In-Buffer Settings
18408 :DESCRIPTION: Overview of keywords.
18409 :ALT_TITLE: In-buffer Settings
18411 #+cindex: in-buffer settings
18412 #+cindex: special keywords
18414 In-buffer settings start with =#+=, followed by a keyword, a colon,
18415 and then a word for each setting. Org accepts multiple settings on
18416 the same line. Org also accepts multiple lines for a keyword. This
18417 manual describes these settings throughout. A summary follows here.
18419 #+cindex: refresh set-up
18420 {{{kbd(C-c C-c)}}} activates any changes to the in-buffer settings.
18421 Closing and reopening the Org file in Emacs also activates the
18424 #+attr_texinfo: :sep ,
18425 - =#+ARCHIVE: %s_done= ::
18427 #+cindex: @samp{ARCHIVE}, keyword
18428 #+vindex: org-archive-location
18429 Sets the archive location of the agenda file. The corresponding
18430 variable is ~org-archive-location~.
18434 #+cindex: @samp{CATEGORY}, keyword
18435 Sets the category of the agenda file, which applies to the entire
18438 - =#+COLUMNS: %25ITEM ...= ::
18440 #+cindex: @samp{COLUMNS}, property
18441 Set the default format for columns view. This format applies when
18442 columns view is invoked in locations where no =COLUMNS= property
18445 - =#+CONSTANTS: name1=value1 ...= ::
18447 #+cindex: @samp{CONSTANTS}, keyword
18448 #+vindex: org-table-formula-constants
18449 #+vindex: org-table-formula
18450 Set file-local values for constants that table formulas can use.
18451 This line sets the local variable
18452 ~org-table-formula-constants-local~. The global version of this
18453 variable is ~org-table-formula-constants~.
18455 - =#+FILETAGS: :tag1:tag2:tag3:= ::
18457 #+cindex: @samp{FILETAGS}, keyword
18458 Set tags that all entries in the file inherit from, including the
18461 - =#+LINK: linkword replace= ::
18463 #+cindex: @samp{LINK}, keyword
18464 #+vindex: org-link-abbrev-alist
18465 Each line specifies one abbreviation for one link. Use multiple
18466 =LINK= keywords for more, see [[*Link Abbreviations]]. The
18467 corresponding variable is ~org-link-abbrev-alist~.
18469 - =#+PRIORITIES: highest lowest default= ::
18471 #+cindex: @samp{PRIORITIES}, keyword
18472 #+vindex: org-highest-priority
18473 #+vindex: org-lowest-priority
18474 #+vindex: org-default-priority
18475 This line sets the limits and the default for the priorities. All
18476 three must be either letters A--Z or numbers 0--9. The highest
18477 priority must have a lower ASCII number than the lowest priority.
18479 - =#+PROPERTY: Property_Name Value= ::
18481 #+cindex: @samp{PROPERTY}, keyword
18482 This line sets a default inheritance value for entries in the
18483 current buffer, most useful for specifying the allowed values of
18486 - =#+SETUPFILE: file= ::
18488 #+cindex: @samp{SETUPFILE}, keyword
18489 The setup file or a URL pointing to such file is for additional
18490 in-buffer settings. Org loads this file and parses it for any
18491 settings in it only when Org opens the main file. If URL is
18492 specified, the contents are downloaded and stored in a temporary
18493 file cache. {{{kbd(C-c C-c)}}} on the settings line parses and
18494 loads the file, and also resets the temporary file cache. Org also
18495 parses and loads the document during normal exporting process. Org
18496 parses the contents of this document as if it was included in the
18497 buffer. It can be another Org file. To visit the file---not
18498 a URL---use {{{kbd(C-c ')}}} while point is on the line with the
18503 #+cindex: @samp{STARTUP}, keyword
18504 Startup options Org uses when first visiting a file.
18506 #+vindex: org-startup-folded
18507 The first set of options deals with the initial visibility of the
18508 outline tree. The corresponding variable for global default
18509 settings is ~org-startup-folded~ with a default value of ~t~, which
18510 is the same as ~overview~.
18514 Top-level headlines only.
18522 No folding on any entry.
18524 - =showeverything= ::
18526 Show even drawer contents.
18528 #+vindex: org-startup-indented
18529 Dynamic virtual indentation is controlled by the variable
18530 ~org-startup-indented~[fn:147].
18534 Start with ~org-indent-mode~ turned on.
18538 Start with ~org-indent-mode~ turned off.
18540 #+vindex: org-startup-align-all-tables
18541 Aligns tables consistently upon visiting a file. The
18542 corresponding variable is ~org-startup-align-all-tables~ with
18543 ~nil~ as default value.
18551 Do not align tables on startup.
18553 #+vindex: org-startup-shrink-all-tables
18554 Shrink table columns with a width cookie. The corresponding
18555 variable is ~org-startup-shrink-all-tables~ with ~nil~ as
18558 #+vindex: org-startup-with-inline-images
18559 When visiting a file, inline images can be automatically
18560 displayed. The corresponding variable is
18561 ~org-startup-with-inline-images~, with a default value ~nil~ to
18562 avoid delays when visiting a file.
18564 - =inlineimages= ::
18566 Show inline images.
18568 - =noinlineimages= ::
18570 Do not show inline images on startup.
18572 #+vindex: org-log-done
18573 #+vindex: org-log-note-clock-out
18574 #+vindex: org-log-repeat
18575 Logging the closing and reopening of TODO items and clock
18576 intervals can be configured using these options (see variables
18577 ~org-log-done~, ~org-log-note-clock-out~, and ~org-log-repeat~).
18581 Record a timestamp when an item is marked DONE.
18585 Record timestamp and a note when DONE.
18589 Do not record when items are marked DONE.
18593 Record a time when reinstating a repeating item.
18595 - =lognoterepeat= ::
18597 Record a note when reinstating a repeating item.
18601 Do not record when reinstating repeating item.
18603 - =lognoteclock-out= ::
18605 Record a note when clocking out.
18607 - =nolognoteclock-out= ::
18609 Do not record a note when clocking out.
18611 - =logreschedule= ::
18613 Record a timestamp when scheduling time changes.
18615 - =lognotereschedule= ::
18617 Record a note when scheduling time changes.
18619 - =nologreschedule= ::
18621 Do not record when a scheduling date changes.
18623 - =logredeadline= ::
18625 Record a timestamp when deadline changes.
18627 - =lognoteredeadline= ::
18629 Record a note when deadline changes.
18631 - =nologredeadline= ::
18633 Do not record when a deadline date changes.
18637 Record a timestamp when refiling.
18639 - =lognoterefile= ::
18641 Record a note when refiling.
18645 Do not record when refiling.
18647 #+vindex: org-hide-leading-stars
18648 #+vindex: org-odd-levels-only
18649 Here are the options for hiding leading stars in outline
18650 headings, and for indenting outlines. The corresponding
18651 variables are ~org-hide-leading-stars~ and
18652 ~org-odd-levels-only~, both with a default setting ~nil~
18653 (meaning =showstars= and =oddeven=).
18657 Make all but one of the stars starting a headline invisible.
18661 Show all stars starting a headline.
18665 Virtual indentation according to outline level.
18669 No virtual indentation according to outline level.
18673 Allow only odd outline levels (1, 3, ...).
18677 Allow all outline levels.
18679 #+vindex: org-put-time-stamp-overlays
18680 #+vindex: org-time-stamp-overlay-formats
18681 To turn on custom format overlays over timestamps (variables
18682 ~org-put-time-stamp-overlays~ and
18683 ~org-time-stamp-overlay-formats~), use:
18687 Overlay custom time format.
18689 #+vindex: constants-unit-system
18690 The following options influence the table spreadsheet (variable
18691 ~constants-unit-system~).
18695 =constants.el= should use the c-g-s unit system.
18699 =constants.el= should use the SI unit system.
18701 #+vindex: org-footnote-define-inline
18702 #+vindex: org-footnote-auto-label
18703 #+vindex: org-footnote-auto-adjust
18704 To influence footnote settings, use the following keywords. The
18705 corresponding variables are ~org-footnote-define-inline~,
18706 ~org-footnote-auto-label~, and ~org-footnote-auto-adjust~.
18710 Define footnotes inline.
18714 Define footnotes in separate section.
18718 Define footnotes near first reference, but not inline.
18722 Prompt for footnote labels.
18726 Create =[fn:1]=-like labels automatically (default).
18730 Offer automatic label for editing or confirmation.
18734 Automatically renumber and sort footnotes.
18738 Do not renumber and sort automatically.
18740 #+vindex: org-hide-block-startup
18741 To hide blocks on startup, use these keywords. The
18742 corresponding variable is ~org-hide-block-startup~.
18746 Hide all begin/end blocks on startup.
18748 - =nohideblocks= ::
18750 Do not hide blocks on startup.
18752 #+vindex: org-pretty-entities
18753 The display of entities as UTF-8 characters is governed by the
18754 variable ~org-pretty-entities~ and the keywords
18756 - =entitiespretty= ::
18758 Show entities as UTF-8 characters where possible.
18760 - =entitiesplain= ::
18762 Leave entities plain.
18764 - =#+TAGS: TAG1(c1) TAG2(c2)= ::
18766 #+cindex: @samp{TAGS}, keyword
18767 #+vindex: org-tag-alist
18768 These lines (several such lines are allowed) specify the valid tags
18769 in this file, and (potentially) the corresponding /fast tag
18770 selection/ keys. The corresponding variable is ~org-tag-alist~.
18772 - =#+TODO:=, =#+SEQ_TODO:=, =#+TYP_TODO:= ::
18774 #+cindex: @samp{SEQ_TODO}, keyword
18775 #+cindex: @samp{TODO}, keyword
18776 #+cindex: @samp{TYP_TODO}, keyword
18777 #+vindex: org-todo-keywords
18778 These lines set the TODO keywords and their interpretation in the
18779 current file. The corresponding variable is ~org-todo-keywords~.
18781 ** The Very Busy {{{kbd(C-c C-c)}}} Key
18783 :DESCRIPTION: When in doubt, press @kbd{C-c C-c}.
18786 #+cindex: @kbd{C-c C-c}, overview
18788 The {{{kbd(C-c C-c)}}} key in Org serves many purposes depending on
18789 the context. It is probably the most over-worked, multi-purpose key
18790 combination in Org. Its uses are well documented throughout this
18791 manual, but here is a consolidated list for easy reference.
18793 - If any highlights shown in the buffer from the creation of a sparse
18794 tree, or from clock display, remove such highlights.
18796 - If point is in one of the special =KEYWORD= lines, scan the buffer
18797 for these lines and update the information. Also reset the Org file
18798 cache used to temporary store the contents of URLs used as values
18799 for keywords like =SETUPFILE=.
18801 - If point is inside a table, realign the table. The table realigns
18802 even if automatic table editor is turned off.
18804 - If point is on a =TBLFM= keyword, re-apply the formulas to the
18807 - If the current buffer is a capture buffer, close the note and file
18808 it. With a prefix argument, also jump to the target location after
18811 - If point is on a =<<<target>>>=, update radio targets and
18812 corresponding links in this buffer.
18814 - If point is on a property line or at the start or end of a property
18815 drawer, offer property commands.
18817 - If point is at a footnote reference, go to the corresponding
18818 definition, and /vice versa/.
18820 - If point is on a statistics cookie, update it.
18822 - If point is in a plain list item with a checkbox, toggle the status
18825 - If point is on a numbered item in a plain list, renumber the ordered
18828 - If point is on the =#+BEGIN= line of a dynamic block, the block is
18831 - If point is at a timestamp, fix the day name in the timestamp.
18833 ** A Cleaner Outline View
18835 :DESCRIPTION: Getting rid of leading stars in the outline.
18836 :ALT_TITLE: Clean View
18838 #+cindex: hiding leading stars
18839 #+cindex: dynamic indentation
18840 #+cindex: odd-levels-only outlines
18841 #+cindex: clean outline view
18843 Org's default outline with stars and no indents can become too
18844 cluttered for short documents. For /book-like/ long documents, the
18845 effect is not as noticeable. Org provides an alternate stars and
18846 indentation scheme, as shown on the right in the following table. It
18847 uses only one star and indents text to line with the heading:
18850 ,* Top level headline | * Top level headline
18851 ,** Second level | * Second level
18852 ,*** Third level | * Third level
18853 some text | some text
18854 ,*** Third level | * Third level
18855 more text | more text
18856 ,* Another top level headline | * Another top level headline
18859 #+cindex: Indent mode
18860 #+findex: org-indent-mode
18861 To turn this mode on, use the minor mode, ~org-indent-mode~. Text
18862 lines that are not headlines are prefixed with spaces to vertically
18863 align with the headline text[fn:148].
18865 #+vindex: org-indent-indentation-per-level
18866 To make more horizontal space, the headlines are shifted by two stars.
18867 This can be configured by the ~org-indent-indentation-per-level~
18868 variable. Only one star on each headline is visible, the rest are
18869 masked with the same font color as the background.
18871 Note that turning on ~org-indent-mode~ sets ~org-hide-leading-stars~
18872 to ~t~ and ~org-adapt-indentation~ to ~nil~.
18874 #+vindex: org-startup-indented
18875 To globally turn on ~org-indent-mode~ for all files, customize the
18876 variable ~org-startup-indented~.
18878 To turn on indenting for individual files, use =STARTUP= keyword as
18881 : #+STARTUP: indent
18883 Indent on startup makes Org use hard spaces to align text with
18884 headings as shown in examples below.
18886 - /Indentation of text below headlines/ ::
18888 Indent text to align with the headline.
18892 more text, now indented
18895 #+vindex: org-adapt-indentation
18896 Org supports this with paragraph filling, line wrapping, and
18897 structure editing, preserving or adapting the indentation as
18898 appropriate[fn:149].
18900 - /Hiding leading stars/ ::
18902 #+vindex: org-hide-leading-stars
18903 Org can make leading stars invisible. For global preference,
18904 configure the variable ~org-hide-leading-stars~. For per-file
18905 preference, use these file =STARTUP= options:
18908 ,#+STARTUP: hidestars
18909 ,#+STARTUP: showstars
18912 With stars hidden, the tree is shown as:
18915 ,* Top level headline
18921 #+vindex: org-hide, face
18922 Because Org makes the font color the same as the background color
18923 to hide to stars, sometimes ~org-hide~ face may need tweaking to
18924 get the effect right. For some black and white combinations,
18925 ~grey90~ on a white background might mask the stars better.
18929 #+vindex: org-odd-levels-only
18930 Using stars for only odd levels, 1, 3, 5, ..., can also clean up the
18931 clutter. This removes two stars from each level[fn:150]. For Org
18932 to properly handle this cleaner structure during edits and exports,
18933 configure the variable ~org-odd-levels-only~. To set this per-file,
18934 use either one of the following lines:
18938 ,#+STARTUP: oddeven
18941 To switch between single and double stars layouts, use {{{kbd(M-x
18942 org-convert-to-odd-levels)}}} and {{{kbd(M-x
18943 org-convert-to-oddeven-levels)}}}.
18945 ** Dynamic Headline Numbering
18947 :DESCRIPTION: Display and update outline numbering.
18950 #+cindex: Org Num mode
18951 #+cindex: number headlines
18952 The Org Num minor mode, toggled with {{{kbd(M-x org-num-mode)}}},
18953 displays on top of headlines. It also updates numbering automatically
18954 upon changes to the structure of the document.
18956 #+vindex: org-num-max-level
18957 #+vindex: org-num-skip-tags
18958 #+vindex: org-num-skip-commented
18959 #+vindex: org-num-skip-unnumbered
18960 By default, all headlines are numbered. You can limit numbering to
18961 specific headlines according to their level, tags, =COMMENT= keyword,
18962 or =UNNUMBERED= property. Set ~org-num-max-level~,
18963 ~org-num-skip-tags~, ~org-num-skip-commented~,
18964 ~org-num-skip-unnumbered~, or ~org-num-skip-footnotes~ accordingly.
18966 #+vindex: org-num-skip-footnotes
18967 If ~org-num-skip-footnotes~ is non-~nil~, footnotes sections (see
18968 [[*Creating Footnotes]]) are not numbered either.
18970 #+vindex: org-num-face
18971 #+vindex: org-num-format-function
18972 You can control how the numbering is displayed by setting
18973 ~org-num-face~ and ~org-num-format-function~.
18975 ** Using Org on a TTY
18977 :DESCRIPTION: Using Org on a tty.
18978 :ALT_TITLE: TTY Keys
18980 #+cindex: tty key bindings
18982 Org provides alternative key bindings for TTY and modern mobile
18983 devices that cannot perform movement commands on point and key
18984 bindings with modifier keys. Some of these workarounds may be more
18985 cumbersome than necessary. Users should look into customizing these
18986 further based on their usage needs. For example, the normal
18987 {{{kbd(S-<cursor>)}}} for editing timestamp might be better with
18988 {{{kbd(C-c .)}}} chord.
18990 #+attr_texinfo: :columns 0.2 0.28 0.15 0.21
18991 | Default | Alternative 1 | Speed key | Alternative 2 |
18992 |----------------------+--------------------------+--------------+----------------------|
18993 | {{{kbd(S-TAB)}}} | {{{kbd(C-u TAB)}}} | {{{kbd(C)}}} | |
18994 | {{{kbd(M-LEFT)}}} | {{{kbd(C-c C-x l)}}} | {{{kbd(l)}}} | {{{kbd(Esc LEFT)}}} |
18995 | {{{kbd(M-S-LEFT)}}} | {{{kbd(C-c C-x L)}}} | {{{kbd(L)}}} | |
18996 | {{{kbd(M-RIGHT)}}} | {{{kbd(C-c C-x r)}}} | {{{kbd(r)}}} | {{{kbd(Esc RIGHT)}}} |
18997 | {{{kbd(M-S-RIGHT)}}} | {{{kbd(C-c C-x R)}}} | {{{kbd(R)}}} | |
18998 | {{{kbd(M-UP)}}} | {{{kbd(C-c C-x u)}}} | | {{{kbd(Esc UP)}}} |
18999 | {{{kbd(M-S-UP)}}} | {{{kbd(C-c C-x U)}}} | {{{kbd(U)}}} | |
19000 | {{{kbd(M-DOWN)}}} | {{{kbd(C-c C-x d)}}} | | {{{kbd(Esc DOWN)}}} |
19001 | {{{kbd(M-S-DOWN)}}} | {{{kbd(C-c C-x D)}}} | {{{kbd(D)}}} | |
19002 | {{{kbd(S-RET)}}} | {{{kbd(C-c C-x c)}}} | | |
19003 | {{{kbd(M-RET)}}} | {{{kbd(C-c C-x m)}}} | | {{{kbd(Esc RET)}}} |
19004 | {{{kbd(M-S-RET)}}} | {{{kbd(C-c C-x M)}}} | | |
19005 | {{{kbd(S-LEFT)}}} | {{{kbd(C-c LEFT)}}} | | |
19006 | {{{kbd(S-RIGHT)}}} | {{{kbd(C-c RIGHT)}}} | | |
19007 | {{{kbd(S-UP)}}} | {{{kbd(C-c UP)}}} | | |
19008 | {{{kbd(S-DOWN)}}} | {{{kbd(C-c DOWN)}}} | | |
19009 | {{{kbd(C-S-LEFT)}}} | {{{kbd(C-c C-x LEFT)}}} | | |
19010 | {{{kbd(C-S-RIGHT)}}} | {{{kbd(C-c C-x RIGHT)}}} | | |
19012 ** Context Dependent Documentation
19014 :DESCRIPTION: Read documentation about current syntax.
19015 :ALT_TITLE: Documentation Access
19017 #+cindex: documentation
19020 #+findex: org-info-find-node
19021 #+kindex: C-c C-x I
19022 {{{kbd(C-c C-x I)}}} in an Org file tries to open a suitable section
19023 of the Org manual depending on the syntax at point. For example,
19024 using it on a headline displays "Document Structure" section.
19026 {{{kbd(q)}}} closes the Info window.
19028 ** Interaction with Other Packages
19030 :DESCRIPTION: With other Emacs packages.
19031 :ALT_TITLE: Interaction
19033 #+cindex: packages, interaction with other
19035 Org's compatibility and the level of interaction with other Emacs
19036 packages are documented here.
19038 *** Packages that Org cooperates with
19040 :DESCRIPTION: Packages Org cooperates with.
19041 :ALT_TITLE: Cooperation
19044 - =calc.el= by Dave Gillespie ::
19045 #+cindex: @file{calc.el}
19047 Org uses the Calc package for implementing spreadsheet functionality
19048 in its tables (see [[*The Spreadsheet]]). Org also uses Calc for
19049 embedded calculations. See [[info:calc::Embedded%20Mode][GNU Emacs Calc Manual]].
19051 - =constants.el= by Carsten Dominik ::
19052 #+cindex: @file{constants.el}
19053 #+vindex: org-table-formula-constants
19055 Org can use names for constants in formulas in tables. Org can also
19056 use calculation suffixes for units, such as =M= for =Mega=. For
19057 a standard collection of such constants, install the =constants=
19058 package. Install version 2.0 of this package, available at
19059 [[http://www.astro.uva.nl/~dominik/Tools]]. Org checks if the function
19060 ~constants-get~ has been autoloaded. Installation instructions are
19061 in the file =constants.el=.
19063 - =cdlatex.el= by Carsten Dominik ::
19064 #+cindex: @file{cdlatex.el}
19066 Org mode can make use of the CDLaTeX package to efficiently enter
19067 LaTeX fragments into Org files. See [[*Using CDLaTeX to enter math]].
19069 - =imenu.el= by Ake Stenhoff and Lars Lindberg ::
19070 #+cindex: @file{imenu.el}
19072 Imenu creates dynamic menus based on an index of items in a file.
19073 Org mode supports Imenu menus. Enable it with a mode hook as
19076 #+begin_src emacs-lisp
19077 (add-hook 'org-mode-hook
19078 (lambda () (imenu-add-to-menubar "Imenu")))
19081 #+vindex: org-imenu-depth
19082 By default the index is two levels deep---you can modify the
19083 depth using the option ~org-imenu-depth~.
19085 - =speedbar.el= by Eric\nbsp{}M.\nbsp{}Ludlam ::
19086 #+cindex: @file{speedbar.el}
19088 Speedbar package creates a special Emacs frame for displaying files
19089 and index items in files. Org mode supports Speedbar; users can
19090 drill into Org files directly from the Speedbar. The {{{kbd(<)}}}
19091 in the Speedbar frame tweaks the agenda commands to that file or to
19094 - =table.el= by Takaaki Ota ::
19095 #+cindex: table editor, @file{table.el}
19096 #+cindex: @file{table.el}
19098 Complex ASCII tables with automatic line wrapping, column- and
19099 row-spanning, and alignment can be created using the Emacs table
19100 package by Takaaki Ota. Org mode recognizes such tables and exports
19101 them properly. {{{kbd(C-c ')}}} to edit these tables in a special
19102 buffer, much like Org's code blocks. Because of interference with
19103 other Org mode functionality, Takaaki Ota tables cannot be edited
19104 directly in the Org buffer.
19106 - {{{kbd(C-c ')}}} (~org-edit-special~) ::
19109 #+findex: org-edit-special
19110 Edit a =table.el= table. Works when point is in a =table.el=
19113 - {{{kbd(C-c ~​)}}} (~org-table-create-with-table.el~) ::
19116 #+findex: org-table-create-with-table.el
19117 Insert a =table.el= table. If there is already a table at point,
19118 this command converts it between the =table.el= format and the Org
19119 mode format. See the documentation string of the command
19120 ~org-convert-table~ for the restrictions under which this is
19123 *** Packages that conflict with Org mode
19125 :DESCRIPTION: Packages that lead to conflicts.
19126 :ALT_TITLE: Conflicts
19129 #+cindex: shift-selection-mode
19130 #+vindex: org-support-shift-select
19131 In Emacs, ~shift-selection-mode~ combines motions of point with shift
19132 key to enlarge regions. Emacs sets this mode by default. This
19133 conflicts with Org's use of {{{kbd(S-<cursor>)}}} commands to change
19134 timestamps, TODO keywords, priorities, and item bullet types, etc.
19135 Since {{{kbd(S-<cursor>)}}} commands outside of specific contexts do
19136 not do anything, Org offers the variable ~org-support-shift-select~
19137 for customization. Org mode accommodates shift selection by (i)
19138 making it available outside of the special contexts where special
19139 commands apply, and (ii) extending an existing active region even if
19140 point moves across a special context.
19142 - =cua.el= by Kim\nbsp{}F.\nbsp{}Storm ::
19144 #+cindex: @file{cua.el}
19145 #+vindex: org-replace-disputed-keys
19146 Org key bindings conflict with {{{kbd(S-<cursor>)}}} keys used by
19147 CUA mode. For Org to relinquish these bindings to CUA mode,
19148 configure the variable ~org-replace-disputed-keys~. When set, Org
19149 moves the following key bindings in Org files, and in the agenda
19150 buffer---but not during date selection.
19152 #+attr_texinfo: :columns 0.4 0.4
19153 | {{{kbd(S-UP)}}} \rArr{} {{{kbd(M-p)}}} | {{{kbd(S-DOWN)}}} \rArr{} {{{kbd(M-n)}}} |
19154 | {{{kbd(S-LEFT)}}} \rArr{} {{{kbd(M--)}}} | {{{kbd(S-RIGHT)}}} \rArr{} {{{kbd(M-+)}}} |
19155 | {{{kbd(C-S-LEFT)}}} \rArr{} {{{kbd(M-S--)}}} | {{{kbd(C-S-RIGHT)}}} \rArr{} {{{kbd(M-S-+)}}} |
19157 #+vindex: org-disputed-keys
19158 Yes, these are unfortunately more difficult to remember. If you
19159 want to have other replacement keys, look at the variable
19160 ~org-disputed-keys~.
19162 - =ecomplete.el= by Lars Magne Ingebrigtsen ::
19164 #+cindex: @file{ecomplete.el}
19165 Ecomplete provides "electric" address completion in address header
19166 lines in message buffers. Sadly Orgtbl mode cuts Ecomplete's power
19167 supply: no completion happens when Orgtbl mode is enabled in message
19168 buffers while entering text in address header lines. If one wants
19169 to use ecomplete one should /not/ follow the advice to automagically
19170 turn on Orgtbl mode in message buffers (see [[*The Orgtbl Minor Mode]]),
19171 but instead---after filling in the message headers---turn on Orgtbl
19172 mode manually when needed in the messages body.
19174 - =filladapt.el= by Kyle Jones ::
19176 #+cindex: @file{filladapt.el}
19177 Org mode tries to do the right thing when filling paragraphs, list
19178 items and other elements. Many users reported problems using both
19179 =filladapt.el= and Org mode, so a safe thing to do is to disable
19180 filladapt like this:
19182 #+begin_src emacs-lisp
19183 (add-hook 'org-mode-hook 'turn-off-filladapt-mode)
19186 - =viper.el= by Michael Kifer ::
19187 #+cindex: @file{viper.el}
19190 Viper uses {{{kbd(C-c /)}}} and therefore makes this key not access
19191 the corresponding Org mode command ~org-sparse-tree~. You need to
19192 find another key for this command, or override the key in
19193 ~viper-vi-global-user-map~ with
19195 #+begin_src emacs-lisp
19196 (define-key viper-vi-global-user-map "C-c /" 'org-sparse-tree)
19199 - =windmove.el= by Hovav Shacham ::
19200 #+cindex: @file{windmove.el}
19202 This package also uses the {{{kbd(S-<cursor>)}}} keys, so everything
19203 written in the paragraph above about CUA mode also applies here. If
19204 you want to make the windmove function active in locations where Org
19205 mode does not have special functionality on {{{kbd(S-<cursor>)}}},
19206 add this to your configuration:
19208 #+begin_src emacs-lisp
19209 ;; Make windmove work in Org mode:
19210 (add-hook 'org-shiftup-final-hook 'windmove-up)
19211 (add-hook 'org-shiftleft-final-hook 'windmove-left)
19212 (add-hook 'org-shiftdown-final-hook 'windmove-down)
19213 (add-hook 'org-shiftright-final-hook 'windmove-right)
19216 - =yasnippet.el= ::
19218 #+cindex: @file{yasnippet.el}
19219 The way Org mode binds the {{{kbd(TAB)}}} key (binding to ~[tab]~
19220 instead of ~"\t"~) overrules YASnippet's access to this key. The
19221 following code fixed this problem:
19223 #+begin_src emacs-lisp
19224 (add-hook 'org-mode-hook
19226 (setq-local yas/trigger-key [tab])
19227 (define-key yas/keymap [tab] 'yas/next-field-or-maybe-expand)))
19230 The latest version of YASnippet does not play well with Org mode.
19231 If the above code does not fix the conflict, start by defining
19232 the following function:
19234 #+begin_src emacs-lisp
19235 (defun yas/org-very-safe-expand ()
19236 (let ((yas/fallback-behavior 'return-nil)) (yas/expand)))
19239 Then, tell Org mode to use that function:
19241 #+begin_src emacs-lisp
19242 (add-hook 'org-mode-hook
19244 (make-variable-buffer-local 'yas/trigger-key)
19245 (setq yas/trigger-key [tab])
19246 (add-to-list 'org-tab-first-hook 'yas/org-very-safe-expand)
19247 (define-key yas/keymap [tab] 'yas/next-field)))
19252 :DESCRIPTION: Encrypting Org files.
19255 Org Crypt encrypts the text of an entry, but not the headline, or
19256 properties. Behind the scene, it uses the Emacs EasyPG library to
19257 encrypt and decrypt files.
19259 #+vindex: org-crypt-tag-matcher
19260 Any text below a headline that has a =crypt= tag is automatically
19261 encrypted when the file is saved. To use a different tag, customize
19262 the ~org-crypt-tag-matcher~ setting.
19264 Here is a suggestion for Org Crypt settings in Emacs init file:
19266 #+begin_src emacs-lisp
19267 (require 'org-crypt)
19268 (org-crypt-use-before-save-magic)
19269 (setq org-tags-exclude-from-inheritance '("crypt"))
19271 (setq org-crypt-key nil)
19272 ;; GPG key to use for encryption
19273 ;; Either the Key ID or set to nil to use symmetric encryption.
19275 (setq auto-save-default nil)
19276 ;; Auto-saving does not cooperate with org-crypt.el: so you need to
19277 ;; turn it off if you plan to use org-crypt.el quite often. Otherwise,
19278 ;; you'll get an (annoying) message each time you start Org.
19280 ;; To turn it off only locally, you can insert this:
19282 ;; # -*- buffer-auto-save-file-name: nil; -*-
19285 It's possible to use different keys for different headings by
19286 specifying the respective key as property =CRYPTKEY=, e.g.:
19289 ,* Totally secret :crypt:
19291 :CRYPTKEY: 0x0123456789012345678901234567890123456789
19295 Excluding the =crypt= tag from inheritance prevents already encrypted
19296 text from being encrypted again.
19300 :DESCRIPTION: Viewing and capture on a mobile device.
19302 #+cindex: smartphone
19304 Org Mobile is a protocol for synchronizing Org files between Emacs and
19305 other applications, e.g., on mobile devices. It enables offline-views
19306 and capture support for an Org mode system that is rooted on a "real"
19307 computer. The external application can also record changes to
19310 This appendix describes Org's support for agenda view formats
19311 compatible with Org Mobile. It also describes synchronizing changes,
19312 such as to notes, between the mobile application and the computer.
19314 To change tags and TODO states in the mobile application, first
19315 customize the variables ~org-todo-keywords~ and ~org-tag-alist~.
19316 These should cover all the important tags and TODO keywords, even if
19317 Org files use only some of them. Though the mobile application is
19318 expected to support in-buffer settings, it is required to understand
19319 TODO states /sets/ (see [[*Setting up keywords for individual files]]) and
19320 /mutually exclusive/ tags (see [[*Setting Tags]]) only for those set in
19323 *** Setting up the staging area
19325 :DESCRIPTION: For the mobile device.
19328 #+vindex: org-mobile-directory
19329 The mobile application needs access to a file directory on
19330 a server[fn:151] to interact with Emacs. Pass its location through
19331 the ~org-mobile-directory~ variable. If you can mount that directory
19332 locally just set the variable to point to that directory:
19334 #+begin_src emacs-lisp
19335 (setq org-mobile-directory "~/orgmobile/")
19338 Alternatively, by using TRAMP (see [[info:tramp][TRAMP User Manual]]),
19339 ~org-mobile-directory~ may point to a remote directory accessible
19340 through, for example, SSH, SCP, or DAVS:
19342 #+begin_src emacs-lisp
19343 (setq org-mobile-directory "/davs:user@remote.host:/org/webdav/")
19346 #+vindex: org-mobile-encryption
19347 With a public server, consider encrypting the files. Org also
19348 requires OpenSSL installed on the local computer. To turn on
19349 encryption, set the same password in the mobile application and in
19350 Emacs. Set the password in the variable
19351 ~org-mobile-use-encryption~[fn:152]. Note that even after the mobile
19352 application encrypts the file contents, the file name remains visible
19353 on the file systems of the local computer, the server, and the mobile
19356 *** Pushing to the mobile application
19358 :DESCRIPTION: Uploading Org files and agendas.
19361 #+findex: org-mobile-push
19362 #+vindex: org-mobile-files
19363 The command ~org-mobile-push~ copies files listed in
19364 ~org-mobile-files~ into the staging area. Files include agenda files
19365 (as listed in ~org-agenda-files~). Customize ~org-mobile-files~ to
19366 add other files. File names are staged with paths relative to
19367 ~org-directory~, so all files should be inside this directory[fn:153].
19369 Push creates a special Org file =agendas.org= with custom agenda views
19370 defined by the user[fn:154].
19372 Finally, Org writes the file =index.org=, containing links to other
19373 files. The mobile application reads this file first from the server
19374 to determine what other files to download for agendas. For faster
19375 downloads, it is expected to only read files whose checksums[fn:155]
19378 *** Pulling from the mobile application
19380 :DESCRIPTION: Integrating captured and flagged items.
19383 #+findex: org-mobile-pull
19384 The command ~org-mobile-pull~ synchronizes changes with the server.
19385 More specifically, it first pulls the Org files for viewing. It then
19386 appends captured entries and pointers to flagged or changed entries to
19387 the file =mobileorg.org= on the server. Org ultimately integrates its
19388 data in an inbox file format, through the following steps:
19391 #+vindex: org-mobile-inbox-for-pull
19392 Org moves all entries found in =mobileorg.org=[fn:156] and appends
19393 them to the file pointed to by the variable
19394 ~org-mobile-inbox-for-pull~. It should reside neither in the
19395 staging area nor on the server. Each captured entry and each
19396 editing event is a top-level entry in the inbox file.
19399 #+cindex: @samp{FLAGGED}, tag
19400 After moving the entries, Org processes changes to the shared
19401 files. Some of them are applied directly and without user
19402 interaction. Examples include changes to tags, TODO state,
19403 headline and body text. Entries requiring further action are
19404 tagged as =FLAGGED=. Org marks entries with problems with an error
19405 message in the inbox. They have to be resolved manually.
19407 3. Org generates an agenda view for flagged entries for user
19408 intervention to clean up. For notes stored in flagged entries, Org
19409 displays them in the echo area when point is on the corresponding
19414 Pressing {{{kbd(?)}}} displays the entire flagged note in another
19415 window. Org also pushes it to the kill ring. To store flagged
19416 note as a normal note, use {{{kbd(? z C-y C-c C-c)}}}. Pressing
19417 {{{kbd(?)}}} twice does these things: first it removes the
19418 =FLAGGED= tag; second, it removes the flagged note from the
19419 property drawer; third, it signals that manual editing of the
19420 flagged entry is now finished.
19422 #+kindex: ? @r{(Agenda dispatcher)}
19423 From the agenda dispatcher, {{{kbd(?)}}} returns to the view to finish
19424 processing flagged entries. Note that these entries may not be the
19425 most recent since the mobile application searches files that were last
19426 pulled. To get an updated agenda view with changes since the last
19431 :DESCRIPTION: Formal description of Org's syntax.
19434 A reference document providing a formal description of Org's syntax is
19435 available as [[https://orgmode.org/worg/dev/org-syntax.html][a draft on Worg]], written and maintained by Nicolas
19436 Goaziou. It defines Org's core internal concepts such as "headlines",
19437 "sections", "affiliated keywords", "(greater) elements" and "objects".
19438 Each part of an Org document belongs to one of the previous
19441 To explore the abstract structure of an Org buffer, run this in
19444 : M-: (org-element-parse-buffer) <RET>
19446 #+texinfo: @noindent
19447 It outputs a list containing the buffer's content represented as an
19448 abstract structure. The export engine relies on the information
19449 stored in this list. Most interactive commands---e.g., for structure
19450 editing---also rely on the syntactic meaning of the surrounding
19453 #+cindex: syntax checker
19456 You can probe the syntax of your documents with the command
19458 : M-x org-lint <RET>
19460 #+texinfo: @noindent
19461 It runs a number of checks to find common mistakes. It then displays
19462 their location in a dedicated buffer, along with a description and
19463 a "trust level", since false-positive are possible. From there, you
19464 can operate on the reports with the following keys:
19466 #+attr_texinfo: :columns 0.22 0.78
19467 | {{{kbd(C-j)}}}, {{{kbd(TAB)}}} | Display the offending line |
19468 | {{{kbd(RET)}}} | Move point to the offending line |
19469 | {{{kbd(g)}}} | Check the document again |
19470 | {{{kbd(h)}}} | Hide all reports from the same checker |
19471 | {{{kbd(i)}}} | Also remove them from all subsequent checks |
19472 | {{{kbd(S)}}} | Sort reports by the column at point |
19476 :DESCRIPTION: How to hack your way around.
19481 This appendix describes some ways a user can extend the functionality
19486 :DESCRIPTION: How to reach into Org's internals.
19490 Org has a large number of hook variables for adding functionality.
19491 This appendix illustrates using a few. A complete list of hooks with
19492 documentation is maintained by the Worg project at
19493 https://orgmode.org/worg/doc.html#hooks.
19497 :DESCRIPTION: Available extensions.
19499 #+cindex: add-on packages
19501 Various authors wrote a large number of add-on packages for Org.
19503 These packages are not part of Emacs, but they are distributed as
19504 contributed packages with the separate release available at
19505 https://orgmode.org. See the =contrib/README= file in the source code
19506 directory for a list of contributed files. Worg page with more
19507 information is at: https://orgmode.org/worg/org-contrib/.
19509 ** Adding Hyperlink Types
19511 :DESCRIPTION: New custom link types.
19513 #+cindex: hyperlinks, adding new types
19515 Org has many built-in hyperlink types (see [[*Hyperlinks]]), and an
19516 interface for adding new link types. The following example shows the
19517 process of adding Org links to Unix man pages, which look like this
19519 : [[man:printf][The printf manual]]
19521 #+texinfo: @noindent
19522 The following =org-man.el= file implements it
19524 #+begin_src emacs-lisp
19525 ;;; org-man.el - Support for links to man pages in Org mode
19528 (org-link-set-parameters "man"
19529 :follow org-man-command
19530 :export #'org-man-export
19531 :store #'org-man-store-link)
19533 (defcustom org-man-command 'man
19534 "The Emacs command to be used to display a man page."
19536 :type '(choice (const man) (const woman)))
19538 (defun org-man-store-link ()
19539 "Store a link to a man page."
19540 (when (memq major-mode '(Man-mode woman-mode))
19541 ;; This is a man page, we do make this link.
19542 (let* ((page (org-man-get-page-name))
19543 (link (concat "man:" page))
19544 (description (format "Man page for %s" page)))
19545 (org-store-link-props
19548 :description description))))
19550 (defun org-man-get-page-name ()
19551 "Extract the page name from the buffer name."
19552 ;; This works for both `Man-mode' and `woman-mode'.
19553 (if (string-match " \\(\\S-+\\)\\*" (buffer-name))
19554 (match-string 1 (buffer-name))
19555 (error "Cannot create link to this man page")))
19557 (defun org-man-export (link description format)
19558 "Export a man page link from Org files."
19559 (let ((path (format "http://man.he.net/?topic=%s§ion=all" link))
19560 (desc (or description link)))
19562 (`html (format "<a target=\"_blank\" href=\"%s\">%s</a>" path desc))
19563 (`latex (format "\\href{%s}{%s}" path desc))
19564 (`texinfo (format "@uref{%s,%s}" path desc))
19565 (`ascii (format "%s (%s)" desc path))
19569 ;;; org-man.el ends here
19572 #+texinfo: @noindent
19573 To activate links to man pages in Org, enter this in the Emacs init
19576 #+begin_src emacs-lisp
19580 #+texinfo: @noindent
19581 A review of =org-man.el=:
19583 1. First, =(require 'org)= ensures =org.el= is loaded.
19587 #+findex: org-link-set-parameters
19588 #+vindex: org-link-parameters
19589 Then ~org-link-set-parameters~ defines a new link type with =man=
19590 prefix and associates functions for following, exporting and
19591 storing such links. See the variable ~org-link-parameters~ for
19592 a complete list of possible associations.
19594 3. The rest of the file implements necessary variables and functions.
19596 For example, ~org-man-store-link~ is responsible for storing a link
19597 when ~org-store-link~ (see [[*Handling Links]]) is called from a buffer
19598 displaying a man page. It first checks if the ~major-mode~ is
19599 appropriate. If check fails, the function returns ~nil~, which
19600 means it isn't responsible for creating a link to the current
19601 buffer. Otherwise the function makes a link string by combining
19602 the =man:= prefix with the man topic. It also provides a default
19603 description. The function ~org-insert-link~ can insert it back
19604 into an Org buffer later on.
19606 ** Adding Export Back-ends
19608 :DESCRIPTION: How to write new export back-ends.
19610 #+cindex: Export, writing back-ends
19612 Org's export engine makes it easy for writing new back-ends. The
19613 framework on which the engine was built makes it easy to derive new
19614 back-ends from existing ones.
19616 #+findex: org-export-define-backend
19617 #+findex: org-export-define-derived-backend
19618 The two main entry points to the export engine are:
19619 ~org-export-define-backend~ and ~org-export-define-derived-backend~.
19620 To grok these functions, see =ox-latex.el= for an example of defining
19621 a new back-end from scratch, and =ox-beamer.el= for an example of
19622 deriving from an existing engine.
19624 For creating a new back-end from scratch, first set its name as
19625 a symbol in an alist consisting of elements and export functions. To
19626 make the back-end visible to the export dispatcher, set ~:menu-entry~
19627 keyword. For export options specific to this back-end, set the
19630 For creating a new back-end from an existing one, set
19631 ~:translate-alist~ to an alist of export functions. This alist
19632 replaces the parent back-end functions.
19634 For complete documentation, see [[https://orgmode.org/worg/dev/org-export-reference.html][the Org Export Reference on Worg]].
19636 ** Tables in Arbitrary Syntax
19638 :DESCRIPTION: Orgtbl for LaTeX and other programs.
19640 #+cindex: tables, in other modes
19641 #+cindex: lists, in other modes
19642 #+cindex: Orgtbl mode
19644 Due to Org's success in handling tables with Orgtbl, a frequently
19645 requested feature is the use of Org's table functions in other modes,
19646 e.g., LaTeX. This would be hard to do in a general way without
19647 complicated customization nightmares. Moreover, that would take Org
19648 away from its simplicity roots that Orgtbl has proven. There is,
19649 however, an alternate approach to accomplishing the same.
19651 This approach involves implementing a custom /translate/ function that
19652 operates on a native Org /source table/ to produce a table in another
19653 format. This strategy would keep the excellently working Orgtbl
19654 simple and isolate complications, if any, confined to the translate
19655 function. To add more alien table formats, we just add more translate
19656 functions. Also the burden of developing custom translate functions
19657 for new table formats is in the hands of those who know those formats
19662 :DESCRIPTION: Sending and receiving radio tables.
19664 #+cindex: radio tables
19666 Radio tables are target locations for translated tables that are not near
19667 their source. Org finds the target location and inserts the translated
19670 The key to finding the target location is the magic words =BEGIN/END
19671 RECEIVE ORGTBL=. They have to appear as comments in the current mode.
19672 If the mode is C, then:
19675 /* BEGIN RECEIVE ORGTBL table_name */
19676 /* END RECEIVE ORGTBL table_name */
19679 At the location of source, Org needs a special line to direct Orgtbl
19680 to translate and to find the target for inserting the translated
19681 table. For example:
19683 #+cindex: @samp{ORGTBL}, keyword
19684 : #+ORGTBL: SEND table_name translation_function arguments ...
19686 #+texinfo: @noindent
19687 =table_name= is the table's reference name, which is also used in the
19688 receiver lines, and the =translation_function= is the Lisp function
19689 that translates. This line, in addition, may also contain alternating
19690 key and value arguments at the end. The translation function gets
19691 these values as a property list. A few standard parameters are
19692 already recognized and acted upon before the translation function is
19697 Skip the first N lines of the table. Hlines do count; include them
19698 if they are to be skipped.
19700 - =:skipcols (n1 n2 ...)= ::
19702 List of columns to be skipped. First Org automatically discards
19703 columns with calculation marks and then sends the table to the
19704 translator function, which then skips columns as specified in
19707 To keep the source table intact in the buffer without being disturbed
19708 when the source file is compiled or otherwise being worked on, use one
19709 of these strategies:
19711 - Place the table in a block comment. For example, in C mode you
19712 could wrap the table between =/*= and =*/= lines.
19714 - Put the table after an "end" statement. For example ~\bye~ in TeX
19715 and ~\end{document}~ in LaTeX.
19717 - Comment and un-comment each line of the table during edits. The
19718 {{{kbd(M-x orgtbl-toggle-comment)}}} command makes toggling easy.
19720 *** A LaTeX example of radio tables
19722 :DESCRIPTION: Step by step, almost a tutorial.
19723 :ALT_TITLE: A LaTeX example
19725 #+cindex: @LaTeX{}, and Orgtbl mode
19727 To wrap a source table in LaTeX, use the =comment= environment
19728 provided by =comment.sty=[fn:157]. To activate it, put
19729 ~\usepackage{comment}~ in the document header. Orgtbl mode inserts
19730 a radio table skeleton[fn:150] with the command {{{kbd(M-x
19731 orgtbl-insert-radio-table)}}}, which prompts for a table name. For
19732 example, if =salesfigures= is the name, the template inserts:
19735 % BEGIN RECEIVE ORGTBL salesfigures
19736 % END RECEIVE ORGTBL salesfigures
19738 ,#+ORGTBL: SEND salesfigures orgtbl-to-latex
19743 #+vindex: LaTeX-verbatim-environments
19744 #+texinfo: @noindent
19745 The line =#+ORGTBL: SEND= tells Orgtbl mode to use the function
19746 ~orgtbl-to-latex~ to convert the table to LaTeX format, then insert
19747 the table at the target (receive) location named =salesfigures=. Now
19748 the table is ready for data entry. It can even use spreadsheet
19752 % BEGIN RECEIVE ORGTBL salesfigures
19753 % END RECEIVE ORGTBL salesfigures
19755 ,#+ORGTBL: SEND salesfigures orgtbl-to-latex
19756 | Month | Days | Nr sold | per day |
19757 |-------+------+---------+---------|
19758 | Jan | 23 | 55 | 2.4 |
19759 | Feb | 21 | 16 | 0.8 |
19760 | March | 22 | 278 | 12.6 |
19761 ,#+TBLFM: $4=$3/$2;%.1f
19762 % $ (optional extra dollar to keep Font Lock happy, see footnote)
19766 After editing, {{{kbd(C-c C-c)}}} inserts the translated table at the
19767 target location, between the two marker lines.
19769 For hand-made custom tables, note that the translator needs to skip
19770 the first two lines of the source table. Also the command has to
19771 /splice/ out the target table without the header and footer.
19774 \begin{tabular}{lrrr}
19775 Month & \multicolumn{1}{c}{Days} & Nr.\ sold & per day\\
19776 % BEGIN RECEIVE ORGTBL salesfigures
19777 % END RECEIVE ORGTBL salesfigures
19781 ,#+ORGTBL: SEND salesfigures orgtbl-to-latex :splice t :skip 2
19782 | Month | Days | Nr sold | per day |
19783 |-------+------+---------+---------|
19784 | Jan | 23 | 55 | 2.4 |
19785 | Feb | 21 | 16 | 0.8 |
19786 | March | 22 | 278 | 12.6 |
19787 ,#+TBLFM: $4=$3/$2;%.1f
19791 The LaTeX translator function ~orgtbl-to-latex~ is already part of
19792 Orgtbl mode and uses a =tabular= environment to typeset the table and
19793 marks horizontal lines with ~\hline~. For additional parameters to
19794 control output, see [[*Translator functions]]:
19796 - =:splice BOOLEAN= ::
19798 When {{{var(BOOLEAN}}} is non-~nil~, return only table body lines;
19799 i.e., not wrapped in =tabular= environment. Default is ~nil~.
19803 Format string to warp each field. It should contain =%s= for the
19804 original field value. For example, to wrap each field value in
19805 dollar symbol, you could use =:fmt "$%s$"=. Format can also wrap
19806 a property list with column numbers and formats, for example =:fmt
19807 (2 "$%s$" 4 "%s\\%%")=. In place of a string, a function of one
19808 argument can be used; the function must return a formatted string.
19812 Format numbers as exponentials. The spec should have =%s= twice for
19813 inserting mantissa and exponent, for example ="%s\\times10^{%s}"=. This
19814 may also be a property list with column numbers and formats, for
19815 example =:efmt (2 "$%s\\times10^{%s}$" 4 "$%s\\cdot10^{%s}$")=. After
19816 {{{var(EFMT)}}} has been applied to a value, {{{var(FMT)}}}---see
19817 above---is also applied. Functions with two arguments can be
19818 supplied instead of strings. By default, no special formatting is
19821 *** Translator functions
19823 :DESCRIPTION: Copy and modify.
19825 #+cindex: HTML, and Orgtbl mode
19826 #+cindex: translator function
19828 #+findex: orgtbl-to-csv
19829 #+findex: orgtbl-to-tsv
19830 #+findex: orgtbl-to-latex
19831 #+findex: orgtbl-to-html
19832 #+findex: orgtbl-to-texinfo
19833 #+findex: orgtbl-to-unicode
19834 #+findex: orgtbl-to-orgtbl
19835 #+findex: orgtbl-to-generic
19836 Orgtbl mode has built-in translator functions: ~orgtbl-to-csv~
19837 (comma-separated values), ~orgtbl-to-tsv~ (TAB-separated values),
19838 ~orgtbl-to-latex~, ~orgtbl-to-html~, ~orgtbl-to-texinfo~,
19839 ~orgtbl-to-unicode~ and ~orgtbl-to-orgtbl~. They use the generic
19840 translator, ~orgtbl-to-generic~, which delegates translations to
19841 various export back-ends.
19843 Properties passed to the function through the =ORGTBL SEND= line take
19844 precedence over properties defined inside the function. For example,
19845 this overrides the default LaTeX line endings, ~\\~, with ~\\[2mm]~:
19847 : #+ORGTBL: SEND test orgtbl-to-latex :lend " \\\\[2mm]"
19849 For a new language translator, define a converter function. It can be
19850 a generic function, such as shown in this example. It marks
19851 a beginning and ending of a table with =!BTBL!= and =!ETBL!=;
19852 a beginning and ending of lines with =!BL!= and =!EL!=; and uses a TAB
19853 for a field separator:
19855 #+begin_src emacs-lisp
19856 (defun orgtbl-to-language (table params)
19857 "Convert the orgtbl-mode TABLE to language."
19860 (org-combine-plists
19861 '(:tstart "!BTBL!" :tend "!ETBL!" :lstart "!BL!" :lend "!EL!" :sep "\t")
19865 #+texinfo: @noindent
19866 The documentation for the ~orgtbl-to-generic~ function shows
19867 a complete list of parameters, each of which can be passed through to
19868 ~orgtbl-to-latex~, ~orgtbl-to-texinfo~, and any other function using
19869 that generic function.
19871 For complicated translations the generic translator function could be
19872 replaced by a custom translator function. Such a custom function must
19873 take two arguments and return a single string containing the formatted
19874 table. The first argument is the table whose lines are a list of
19875 fields or the symbol ~hline~. The second argument is the property
19876 list consisting of parameters specified in the =#+ORGTBL: SEND= line.
19877 Please share your translator functions by posting them to the Org
19878 users mailing list, at mailto:emacs-orgmode@gnu.org.
19882 :DESCRIPTION: Automatically filled blocks.
19884 #+cindex: dynamic blocks
19886 Org supports /dynamic blocks/ in Org documents. They are inserted
19887 with begin and end markers like any other code block, but the contents
19888 are updated automatically by a user function.
19890 #+kindex: C-c C-x x
19891 #+findex: org-dynamic-block-insert-dblock
19892 You can insert a dynamic block with ~org-dynamic-block-insert-dblock~,
19893 which is bound to {{{kbd(C-c C-x x)}}} by default. For example,
19894 {{{kbd(C-c C-x x c l o c k t a b l e RET)}}} inserts a table that
19895 updates the work time (see [[*Clocking Work Time]]).
19897 Dynamic blocks can have names and function parameters. The syntax is
19898 similar to source code block specifications:
19901 ,#+BEGIN: myblock :parameter1 value1 :parameter2 value2 ...
19906 These commands update dynamic blocks:
19908 - {{{kbd(C-c C-x C-u)}}} (~org-dblock-update~) ::
19910 #+kindex: C-c C-x C-u
19911 #+findex: org-dblock-update
19912 Update dynamic block at point.
19914 - {{{kbd(C-u C-c C-x C-u)}}} ::
19916 #+kindex: C-u C-c C-x C-u
19917 Update all dynamic blocks in the current file.
19919 Before updating a dynamic block, Org removes content between the
19920 =BEGIN= and =END= markers. Org then reads the parameters on the
19921 =BEGIN= line for passing to the writer function. If the function
19922 expects to access the removed content, then Org expects an extra
19923 parameter, =:content=, on the =BEGIN= line.
19925 The syntax for naming a writer function with a dynamic block labelled
19926 =myblock= is: ~org-dblock-write:myblock~. Parameters come from the
19929 The following is an example of a dynamic block and a block writer function
19930 that updates the time when the function was last run:
19933 ,#+BEGIN: block-update-time :format "on %m/%d/%Y at %H:%M"
19938 #+texinfo: @noindent
19939 The dynamic block's writer function:
19941 #+begin_src emacs-lisp
19942 (defun org-dblock-write:block-update-time (params)
19943 (let ((fmt (or (plist-get params :format) "%d. %m. %Y")))
19944 (insert "Last block update at: "
19945 (format-time-string fmt))))
19948 To keep dynamic blocks up-to-date in an Org file, use the function,
19949 ~org-update-all-dblocks~ in hook, such as ~before-save-hook~. The
19950 ~org-update-all-dblocks~ function does not run if the file is not in
19953 #+findex: org-narrow-to-block
19954 Dynamic blocks, like any other block, can be narrowed with
19955 ~org-narrow-to-block~.
19957 ** Special Agenda Views
19959 :DESCRIPTION: Customized views.
19961 #+cindex: agenda views, user-defined
19963 #+vindex: org-agenda-skip-function
19964 #+vindex: org-agenda-skip-function-global
19965 Org provides a special hook to further limit items in agenda views:
19966 ~agenda~, ~agenda*~[fn:159], ~todo~, ~alltodo~, ~tags~, ~tags-todo~,
19967 ~tags-tree~. Specify a custom function that tests inclusion of every
19968 matched item in the view. This function can also skip as much as is
19971 For a global condition applicable to agenda views, use the
19972 ~org-agenda-skip-function-global~ variable. Org uses a global
19973 condition with ~org-agenda-skip-function~ for custom searching.
19975 This example defines a function for a custom view showing TODO items
19976 with =waiting= status. Manually this is a multi-step search process,
19977 but with a custom view, this can be automated as follows:
19979 The custom function searches the subtree for the =waiting= tag and
19980 returns ~nil~ on match. Otherwise it gives the location from where
19981 the search continues.
19983 #+begin_src emacs-lisp
19984 (defun my-skip-unless-waiting ()
19985 "Skip trees that are not waiting"
19986 (let ((subtree-end (save-excursion (org-end-of-subtree t))))
19987 (if (re-search-forward ":waiting:" subtree-end t)
19988 nil ; tag found, do not skip
19989 subtree-end))) ; tag not found, continue after end of subtree
19992 To use this custom function in a custom agenda command:
19994 #+begin_src emacs-lisp
19995 (org-add-agenda-custom-command
19996 '("b" todo "PROJECT"
19997 ((org-agenda-skip-function 'my-skip-unless-waiting)
19998 (org-agenda-overriding-header "Projects waiting for something: "))))
20001 #+vindex: org-agenda-overriding-header
20002 Note that this also binds ~org-agenda-overriding-header~ to a more
20003 meaningful string suitable for the agenda view.
20005 #+vindex: org-odd-levels-only
20006 #+vindex: org-agenda-skip-function
20007 Search for entries with a limit set on levels for the custom search.
20008 This is a general approach to creating custom searches in Org. To
20009 include all levels, use =LEVEL>0=[fn:160]. Then to selectively pick
20010 the matched entries, use ~org-agenda-skip-function~, which also
20011 accepts Lisp forms, such as ~org-agenda-skip-entry-if~ and
20012 ~org-agenda-skip-subtree-if~. For example:
20014 - =(org-agenda-skip-entry-if 'scheduled)= ::
20016 Skip current entry if it has been scheduled.
20018 - =(org-agenda-skip-entry-if 'notscheduled)= ::
20020 Skip current entry if it has not been scheduled.
20022 - =(org-agenda-skip-entry-if 'deadline)= ::
20024 Skip current entry if it has a deadline.
20026 - =(org-agenda-skip-entry-if 'scheduled 'deadline)= ::
20028 Skip current entry if it has a deadline, or if it is scheduled.
20030 - =(org-agenda-skip-entry-if 'todo '("TODO" "WAITING"))= ::
20032 Skip current entry if the TODO keyword is TODO or WAITING.
20034 - =(org-agenda-skip-entry-if 'todo 'done)= ::
20036 Skip current entry if the TODO keyword marks a DONE state.
20038 - =(org-agenda-skip-entry-if 'timestamp)= ::
20040 Skip current entry if it has any timestamp, may also be deadline or
20043 - =(org-agenda-skip-entry-if 'regexp "regular expression")= ::
20045 Skip current entry if the regular expression matches in the entry.
20047 - =(org-agenda-skip-entry-if 'notregexp "regular expression")= ::
20049 Skip current entry unless the regular expression matches.
20051 - =(org-agenda-skip-subtree-if 'regexp "regular expression")= ::
20053 Same as above, but check and skip the entire subtree.
20055 The following is an example of a search for =waiting= without the
20058 #+begin_src emacs-lisp
20059 (org-add-agenda-custom-command
20060 '("b" todo "PROJECT"
20061 ((org-agenda-skip-function '(org-agenda-skip-subtree-if
20062 'regexp ":waiting:"))
20063 (org-agenda-overriding-header "Projects waiting for something: "))))
20066 ** Speeding Up Your Agendas
20068 :DESCRIPTION: Tips on how to speed up your agendas.
20070 #+cindex: agenda views, optimization
20072 Some agenda commands slow down when the Org files grow in size or
20073 number. Here are tips to speed up:
20075 - Reduce the number of Org agenda files to avoid slowdowns due to hard drive
20078 - Reduce the number of DONE and archived headlines so agenda
20079 operations that skip over these can finish faster.
20081 - Do not dim blocked tasks:
20082 #+vindex: org-agenda-dim-blocked-tasks
20084 #+begin_src emacs-lisp
20085 (setq org-agenda-dim-blocked-tasks nil)
20088 - Stop preparing agenda buffers on startup:
20089 #+vindex: org-startup-folded
20090 #+vindex: org-agenda-inhibit-startup
20092 #+begin_src emacs-lisp
20093 (setq org-agenda-inhibit-startup t)
20096 - Disable tag inheritance for agendas:
20097 #+vindex: org-agenda-show-inherited-tags
20098 #+vindex: org-agenda-use-tag-inheritance
20100 #+begin_src emacs-lisp
20101 (setq org-agenda-use-tag-inheritance nil)
20104 These options can be applied to selected agenda views. For more
20105 details about generation of agenda views, see the docstrings for the
20106 relevant variables, and this [[https://orgmode.org/worg/agenda-optimization.html][dedicated Worg page]] for agenda
20109 ** Extracting Agenda Information
20111 :DESCRIPTION: Post-processing agenda information.
20113 #+cindex: agenda, pipe
20114 #+cindex: scripts, for agenda processing
20116 Org provides commands to access agendas through Emacs batch mode.
20117 Through this command-line interface, agendas are automated for further
20118 processing or printing.
20120 #+vindex: org-agenda-custom-commands
20121 #+findex: org-batch-agenda
20122 ~org-batch-agenda~ creates an agenda view in ASCII and outputs to
20123 standard output. This command takes one string parameter. When
20124 string consists of a single character, Org uses it as a key to
20125 ~org-agenda-custom-commands~. These are the same ones available
20126 through the agenda dispatcher (see [[*The Agenda Dispatcher]]).
20128 This example command line directly prints the TODO list to the printer:
20130 : emacs -batch -l ~/.emacs -eval '(org-batch-agenda "t")' | lpr
20132 When the string parameter length is two or more characters, Org
20133 matches it with tags/TODO strings. For example, this example command
20134 line prints items tagged with =shop=, but excludes items tagged with
20138 emacs -batch -l ~/.emacs \
20139 -eval '(org-batch-agenda "+shop-NewYork")' | lpr
20142 #+texinfo: @noindent
20143 An example showing on-the-fly parameter modifications:
20146 emacs -batch -l ~/.emacs \
20147 -eval '(org-batch-agenda "a" \
20148 org-agenda-span (quote month) \
20149 org-agenda-include-diary nil \
20150 org-agenda-files (quote ("~/org/project.org")))' \
20154 #+texinfo: @noindent
20155 which produces an agenda for the next 30 days from just the
20156 =~/org/projects.org= file.
20158 #+findex: org-batch-agenda-csv
20159 For structured processing of agenda output, use ~org-batch-agenda-csv~
20160 with the following fields:
20162 - category :: The category of the item
20163 - head :: The headline, without TODO keyword, TAGS and PRIORITY
20164 - type :: The type of the agenda entry, can be
20166 | ~todo~ | selected in TODO match |
20167 | ~tagsmatch~ | selected in tags match |
20168 | ~diary~ | imported from diary |
20169 | ~deadline~ | a deadline |
20170 | ~scheduled~ | scheduled |
20171 | ~timestamp~ | appointment, selected by timestamp |
20172 | ~closed~ | entry was closed on date |
20173 | ~upcoming-deadline~ | warning about nearing deadline |
20174 | ~past-scheduled~ | forwarded scheduled item |
20175 | ~block~ | entry has date block including date |
20177 - todo :: The TODO keyword, if any
20178 - tags :: All tags including inherited ones, separated by colons
20179 - date :: The relevant date, like =2007-2-14=
20180 - time :: The time, like =15:00-16:50=
20181 - extra :: String with extra planning info
20182 - priority-l :: The priority letter if any was given
20183 - priority-n :: The computed numerical priority
20185 If the selection of the agenda item was based on a timestamp,
20186 including those items with =DEADLINE= and =SCHEDULED= keywords, then
20187 Org includes date and time in the output.
20189 If the selection of the agenda item was based on a timestamp (or
20190 deadline/scheduled), then Org includes date and time in the output.
20192 Here is an example of a post-processing script in Perl. It takes the
20193 CSV output from Emacs and prints with a checkbox:
20198 # define the Emacs command to run
20199 $cmd = "emacs -batch -l ~/.emacs -eval '(org-batch-agenda-csv \"t\")'";
20201 # run it and capture the output
20202 $agenda = qx{$cmd 2>/dev/null};
20204 # loop over all lines
20205 foreach $line (split(/\n/,$agenda)) {
20206 # get the individual values
20207 ($category,$head,$type,$todo,$tags,$date,$time,$extra,
20208 $priority_l,$priority_n) = split(/,/,$line);
20209 # process and print
20210 print "[ ] $head\n";
20214 ** Using the Property API
20216 :DESCRIPTION: Writing programs that use entry properties.
20218 #+cindex: API, for properties
20219 #+cindex: properties, API
20221 Here is a description of the functions that can be used to work with
20224 #+attr_texinfo: :options org-entry-properties &optional pom which
20226 Get all properties of the entry at point-or-marker {{{var(POM)}}}.
20227 This includes the TODO keyword, the tags, time strings for deadline,
20228 scheduled, and clocking, and any additional properties defined in the
20229 entry. The return value is an alist. Keys may occur multiple times
20230 if the property key was used several times. {{{var(POM)}}} may also
20231 be ~nil~, in which case the current entry is used. If
20232 {{{var(WHICH)}}} is ~nil~ or ~all~, get all properties. If
20233 {{{var(WHICH)}}} is ~special~ or ~standard~, only get that subclass.
20236 #+vindex: org-use-property-inheritance
20237 #+findex: org-insert-property-drawer
20238 #+attr_texinfo: :options org-entry-get pom property &optional inherit
20240 Get value of {{{var(PROPERTY)}}} for entry at point-or-marker
20241 {{{var(POM)}}}. By default, this only looks at properties defined
20242 locally in the entry. If {{{var(INHERIT)}}} is non-~nil~ and the
20243 entry does not have the property, then also check higher levels of the
20244 hierarchy. If {{{var(INHERIT)}}} is the symbol ~selective~, use
20245 inheritance if and only if the setting of
20246 ~org-use-property-inheritance~ selects {{{var(PROPERTY)}}} for
20250 #+attr_texinfo: :options org-entry-delete pom property
20252 Delete the property {{{var(PROPERTY)}}} from entry at point-or-marker
20256 #+attr_texinfo: :options org-entry-put pom property value
20258 Set {{{var(PROPERTY)}}} to {{{var(VALUES)}}} for entry at
20259 point-or-marker POM.
20262 #+attr_texinfo: :options org-buffer-property-keys &optional include-specials
20264 Get all property keys in the current buffer.
20267 #+attr_texinfo: :options org-insert-property-drawer
20269 Insert a property drawer for the current entry. Also
20272 #+attr_texinfo: :options org-entry-put-multivalued-property pom property &rest values
20274 Set {{{var(PROPERTY)}}} at point-or-marker {{{var(POM)}}} to
20275 {{{var(VALUES)}}}. {{{var(VALUES)}}} should be a list of strings.
20276 They are concatenated, with spaces as separators.
20279 #+attr_texinfo: :options org-entry-get-multivalued-property pom property
20281 Treat the value of the property {{{var(PROPERTY)}}} as
20282 a whitespace-separated list of values and return the values as a list
20286 #+attr_texinfo: :options org-entry-add-to-multivalued-property pom property value
20288 Treat the value of the property {{{var(PROPERTY)}}} as
20289 a whitespace-separated list of values and make sure that
20290 {{{var(VALUE)}}} is in this list.
20293 #+attr_texinfo: :options org-entry-remove-from-multivalued-property pom property value
20295 Treat the value of the property {{{var(PROPERTY)}}} as
20296 a whitespace-separated list of values and make sure that
20297 {{{var(VALUE)}}} is /not/ in this list.
20300 #+attr_texinfo: :options org-entry-member-in-multivalued-property pom property value
20302 Treat the value of the property {{{var(PROPERTY)}}} as
20303 a whitespace-separated list of values and check if {{{var(VALUE)}}} is
20307 #+attr_texinfo: :options org-property-allowed-value-functions
20309 Hook for functions supplying allowed values for a specific property.
20310 The functions must take a single argument, the name of the property,
20311 and return a flat list of allowed values. If =:ETC= is one of the
20312 values, use the values as completion help, but allow also other values
20313 to be entered. The functions must return ~nil~ if they are not
20314 responsible for this property.
20317 ** Using the Mapping API
20319 :DESCRIPTION: Mapping over all or selected entries.
20321 #+cindex: API, for mapping
20322 #+cindex: mapping entries, API
20324 Org has sophisticated mapping capabilities to find all entries
20325 satisfying certain criteria. Internally, this functionality is used
20326 to produce agenda views, but there is also an API that can be used to
20327 execute arbitrary functions for each or selected entries. The main
20328 entry point for this API is:
20330 #+attr_texinfo: :options org-map-entries func &optional match scope &rest skip
20332 Call {{{var(FUNC)}}} at each headline selected by {{{var(MATCH)}}} in
20335 {{{var(FUNC)}}} is a function or a Lisp form. With point positioned
20336 at the beginning of the headline, call the function without arguments.
20337 Org returns an alist of return values of calls to the function.
20339 To avoid preserving point, Org wraps the call to {{{var(FUNC)}}} in
20340 ~save-excursion~ form. After evaluation, Org moves point to the end
20341 of the line that was just processed. Search continues from that point
20342 forward. This may not always work as expected under some conditions,
20343 such as if the current sub-tree was removed by a previous archiving
20344 operation. In such rare circumstances, Org skips the next entry
20345 entirely when it should not. To stop Org from such skips, make
20346 {{{var(FUNC)}}} set the variable ~org-map-continue-from~ to a specific
20349 {{{var(MATCH)}}} is a tags/property/TODO match. Org iterates only
20350 matched headlines. Org iterates over all headlines when
20351 {{{var(MATCH)}}} is ~nil~ or ~t~.
20353 {{{var(SCOPE)}}} determines the scope of this command. It can be any
20358 The current buffer, respecting the restriction, if any.
20362 The subtree started with the entry at point.
20366 The entries within the active region, if any.
20370 The current buffer, without restriction.
20372 - ~file-with-archives~ ::
20374 The current buffer, and any archives associated with it.
20380 - ~agenda-with-archives~ ::
20382 All agenda files with any archive files associated with them.
20384 - list of filenames ::
20386 If this is a list, all files in the list are scanned.
20388 #+texinfo: @noindent
20389 The remaining arguments are treated as settings for the scanner's
20390 skipping facilities. Valid arguments are:
20394 Skip trees with the =ARCHIVE= tag.
20398 Skip trees with the COMMENT keyword.
20400 - function or Lisp form ::
20402 #+vindex: org-agenda-skip-function
20403 Used as value for ~org-agenda-skip-function~, so whenever the
20404 function returns ~t~, {{{var(FUNC)}}} is called for that entry and
20405 search continues from the point where the function leaves it.
20408 The mapping routine can call any arbitrary function, even functions
20409 that change meta data or query the property API (see [[*Using the
20410 Property API]]). Here are some handy functions:
20412 #+attr_texinfo: :options org-todo &optional arg
20414 Change the TODO state of the entry. See the docstring of the
20415 functions for the many possible values for the argument
20419 #+attr_texinfo: :options org-priority &optional action
20421 Change the priority of the entry. See the docstring of this function
20422 for the possible values for {{{var(ACTION)}}}.
20425 #+attr_texinfo: :options org-toggle-tag tag &optional onoff
20427 Toggle the tag {{{var(TAG)}}} in the current entry. Setting
20428 {{{var(ONOFF)}}} to either ~on~ or ~off~ does not toggle tag, but
20429 ensure that it is either on or off.
20432 #+attr_texinfo: :options org-promote
20434 Promote the current entry.
20437 #+attr_texinfo: :options org-demote
20439 Demote the current entry.
20442 This example turns all entries tagged with =TOMORROW= into TODO
20443 entries with keyword =UPCOMING=. Org ignores entries in comment trees
20446 #+begin_src emacs-lisp
20447 (org-map-entries '(org-todo "UPCOMING")
20448 "+TOMORROW" 'file 'archive 'comment)
20451 The following example counts the number of entries with TODO keyword
20452 =WAITING=, in all agenda files.
20454 #+begin_src emacs-lisp
20455 (length (org-map-entries t "/+WAITING" 'agenda))
20458 * History and Acknowledgments
20460 :DESCRIPTION: How Org came into being.
20469 Org was born in 2003, out of frustration over the user interface of
20470 the Emacs Outline mode. I was trying to organize my notes and
20471 projects, and using Emacs seemed to be the natural way to go.
20472 However, having to remember eleven different commands with two or
20473 three keys per command, only to hide and show parts of the outline
20474 tree, that seemed entirely unacceptable to me. Also, when using
20475 outlines to take notes, I constantly wanted to restructure the tree,
20476 organizing it parallel to my thoughts and plans. /Visibility cycling/
20477 and /structure editing/ were originally implemented in the package
20478 =outline-magic.el=, but quickly moved to the more general =org.el=.
20479 As this environment became comfortable for project planning, the next
20480 step was adding /TODO entries/, basic /timestamps/, and /table
20481 support/. These areas highlighted the two main goals that Org still
20482 has today: to be a new, outline-based, plain text mode with innovative
20483 and intuitive editing features, and to incorporate project planning
20484 functionality directly into a notes file.
20486 Since the first release, literally thousands of emails to me or to the
20487 [[mailto:emacs-orgmode@gnu.org][mailing list]] have provided a constant stream of bug reports, feedback,
20488 new ideas, and sometimes patches and add-on code. Many thanks to
20489 everyone who has helped to improve this package. I am trying to keep
20490 here a list of the people who had significant influence in shaping one
20491 or more aspects of Org. The list may not be complete, if I have
20492 forgotten someone, please accept my apologies and let me know.
20494 Before I get to this list, a few special mentions are in order:
20496 - Bastien Guerry ::
20498 Bastien has written a large number of extensions to Org (most of
20499 them integrated into the core by now), including the LaTeX exporter
20500 and the plain list parser. His support during the early days was
20501 central to the success of this project. Bastien also invented Worg,
20502 helped establishing the Web presence of Org, and sponsored hosting
20503 costs for the orgmode.org website. Bastien stepped in as maintainer
20504 of Org between 2011 and 2013, at a time when I desperately needed
20507 - Eric Schulte and Dan Davison ::
20509 Eric and Dan are jointly responsible for the Org Babel system, which
20510 turns Org into a multi-language environment for evaluating code and
20511 doing literate programming and reproducible research. This has
20512 become one of Org's killer features that define what Org is today.
20516 John has contributed a number of great ideas and patches directly to
20517 Org, including the attachment system (=org-attach.el=), integration
20518 with Apple Mail (=org-mac-message.el=), hierarchical dependencies of
20519 TODO items, habit tracking (=org-habits.el=), and encryption
20520 (=org-crypt.el=). Also, the capture system is really an extended
20521 copy of his great =remember.el=.
20523 - Sebastian Rose ::
20525 Without Sebastian, the HTML/XHTML publishing of Org would be the
20526 pitiful work of an ignorant amateur. Sebastian has pushed this part
20527 of Org onto a much higher level. He also wrote =org-info.js=,
20528 a Java script for displaying webpages derived from Org using an
20529 Info-like or a folding interface with single-key navigation.
20531 See below for the full list of contributions! Again, please let me
20532 know what I am missing here!
20539 I (Bastien) have been maintaining Org between 2011 and 2013. This
20540 appendix would not be complete without adding a few more
20541 acknowledgments and thanks.
20543 I am first grateful to Carsten for his trust while handing me over the
20544 maintainership of Org. His unremitting support is what really helped
20545 me getting more confident over time, with both the community and the
20548 When I took over maintainership, I knew I would have to make Org more
20549 collaborative than ever, as I would have to rely on people that are
20550 more knowledgeable than I am on many parts of the code. Here is
20551 a list of the persons I could rely on, they should really be
20552 considered co-maintainers, either of the code or the community:
20556 Eric is maintaining the Babel parts of Org. His reactivity here
20557 kept me away from worrying about possible bugs here and let me focus
20560 - Nicolas Goaziou ::
20562 Nicolas is maintaining the consistency of the deepest parts of Org.
20563 His work on =org-element.el= and =ox.el= has been outstanding, and
20564 it opened the doors for many new ideas and features. He rewrote
20565 many of the old exporters to use the new export engine, and helped
20566 with documenting this major change. More importantly (if that's
20567 possible), he has been more than reliable during all the work done
20568 for Org 8.0, and always very reactive on the mailing list.
20572 Achim rewrote the building process of Org, turning some /ad hoc/
20573 tools into a flexible and conceptually clean process. He patiently
20574 coped with the many hiccups that such a change can create for users.
20578 The Org mode mailing list would not be such a nice place without
20579 Nick, who patiently helped users so many times. It is impossible to
20580 overestimate such a great help, and the list would not be so active
20583 I received support from so many users that it is clearly impossible to
20584 be fair when shortlisting a few of them, but Org's history would not
20585 be complete if the ones above were not mentioned in this manual.
20587 ** List of Contributions
20592 - Russel Adams came up with the idea for drawers.
20594 - Thomas Baumann wrote =org-bbdb.el= and =org-mhe.el=.
20596 - Christophe Bataillon created the great unicorn logo that we use on
20597 the Org mode website.
20599 - Alex Bochannek provided a patch for rounding timestamps.
20601 - Jan Böcker wrote =org-docview.el=.
20603 - Brad Bozarth showed how to pull RSS feed data into Org files.
20605 - Tom Breton wrote =org-choose.el=.
20607 - Charles Cave's suggestion sparked the implementation of templates
20608 for Remember, which are now templates for capture.
20610 - Pavel Chalmoviansky influenced the agenda treatment of items with
20613 - Gregory Chernov patched support for Lisp forms into table
20614 calculations and improved XEmacs compatibility, in particular by
20615 porting =nouline.el= to XEmacs.
20617 - Sacha Chua suggested copying some linking code from Planner.
20619 - Baoqiu Cui contributed the DocBook exporter.
20621 - Eddward DeVilla proposed and tested checkbox statistics. He also
20622 came up with the idea of properties, and that there should be an API
20625 - Nick Dokos tracked down several nasty bugs.
20627 - Kees Dullemond used to edit projects lists directly in HTML and so
20628 inspired some of the early development, including HTML export. He
20629 also asked for a way to narrow wide table columns.
20631 - Thomas\nbsp{}S.\nbsp{}Dye contributed documentation on Worg and helped
20632 integrating the Org Babel documentation into the manual.
20634 - Christian Egli converted the documentation into Texinfo format,
20635 inspired the agenda, patched CSS formatting into the HTML exporter,
20636 and wrote =org-taskjuggler.el=.
20638 - David Emery provided a patch for custom CSS support in exported HTML
20641 - Nic Ferrier contributed mailcap and XOXO support.
20643 - Miguel\nbsp{}A.\nbsp{}Figueroa-Villanueva implemented hierarchical checkboxes.
20645 - John Foerch figured out how to make incremental search show context
20646 around a match in a hidden outline tree.
20648 - Raimar Finken wrote =org-git-line.el=.
20650 - Mikael Fornius works as a mailing list moderator.
20652 - Austin Frank works as a mailing list moderator.
20654 - Eric Fraga drove the development of Beamer export with ideas and
20657 - Barry Gidden did proofreading the manual in preparation for the book
20658 publication through Network Theory Ltd.
20660 - Niels Giesen had the idea to automatically archive DONE trees.
20662 - Nicolas Goaziou rewrote much of the plain list code.
20664 - Kai Grossjohann pointed out key-binding conflicts with other
20667 - Brian Gough of Network Theory Ltd publishes the Org mode manual as
20670 - Bernt Hansen has driven much of the support for auto-repeating
20671 tasks, task state change logging, and the clocktable. His clear
20672 explanations have been critical when we started to adopt the Git
20673 version control system.
20675 - Manuel Hermenegildo has contributed various ideas, small fixes and
20678 - Phil Jackson wrote =org-irc.el=.
20680 - Scott Jaderholm proposed footnotes, control over whitespace between
20681 folded entries, and column view for properties.
20683 - Matt Jones wrote MobileOrg Android.
20685 - Tokuya Kameshima wrote =org-wl.el= and =org-mew.el=.
20687 - Shidai Liu ("Leo") asked for embedded LaTeX and tested it. He also
20688 provided frequent feedback and some patches.
20690 - Matt Lundin has proposed last-row references for table formulas and
20691 named invisible anchors. He has also worked a lot on the FAQ.
20693 - David Maus wrote =org-atom.el=, maintains the issues file for Org,
20694 and is a prolific contributor on the mailing list with competent
20695 replies, small fixes and patches.
20697 - Jason\nbsp{}F.\nbsp{}McBrayer suggested agenda export to CSV format.
20699 - Max Mikhanosha came up with the idea of refiling.
20701 - Dmitri Minaev sent a patch to set priority limits on a per-file
20704 - Stefan Monnier provided a patch to keep the Emacs Lisp compiler
20707 - Richard Moreland wrote MobileOrg for the iPhone.
20709 - Rick Moynihan proposed allowing multiple TODO sequences in a file
20710 and being able to quickly restrict the agenda to a subtree.
20712 - Todd Neal provided patches for links to Info files and Elisp forms.
20714 - Greg Newman refreshed the unicorn logo into its current form.
20716 - Tim O'Callaghan suggested in-file links, search options for general
20717 file links, and tags.
20719 - Osamu Okano wrote =orgcard2ref.pl=, a Perl program to create a text
20720 version of the reference card.
20722 - Takeshi Okano translated the manual and David O'Toole's tutorial
20725 - Oliver Oppitz suggested multi-state TODO items.
20727 - Scott Otterson sparked the introduction of descriptive text for
20728 links, among other things.
20730 - Pete Phillips helped during the development of the TAGS feature,
20731 and provided frequent feedback.
20733 - Martin Pohlack provided the code snippet to bundle character
20734 insertion into bundles of 20 for undo.
20736 - T.\nbsp{}V.\nbsp{}Raman reported bugs and suggested improvements.
20738 - Matthias Rempe (Oelde) provided ideas, Windows support, and quality
20741 - Paul Rivier provided the basic implementation of named footnotes.
20742 He also acted as mailing list moderator for some time.
20744 - Kevin Rogers contributed code to access VM files on remote hosts.
20746 - Frank Ruell solved the mystery of the =keymapp nil= bug, a conflict
20749 - Jason Riedy generalized the send-receive mechanism for Orgtbl
20750 tables with extensive patches.
20752 - Philip Rooke created the Org reference card, provided lots of
20753 feedback, developed and applied standards to the Org documentation.
20755 - Christian Schlauer proposed angular brackets around links, among
20758 - Paul Sexton wrote =org-ctags.el=.
20760 - Tom Shannon's =organizer-mode.el= inspired linking to VM/BBDB/Gnus.
20762 - Ilya Shlyakhter proposed the Archive Sibling, line numbering in
20763 literal examples, and remote highlighting for referenced code lines.
20765 - Stathis Sideris wrote the =ditaa.jar= ASCII to PNG converter that is
20766 now packaged into Org's =contrib/= directory.
20768 - Daniel Sinder came up with the idea of internal archiving by locking
20771 - Dale Smith proposed link abbreviations.
20773 - James TD Smith has contributed a large number of patches for
20774 useful tweaks and features.
20776 - Adam Spiers asked for global linking commands, inspired the link
20777 extension system, added support for Mairix, and proposed the mapping
20780 - Ulf Stegemann created the table to translate special symbols to
20781 HTML, LaTeX, UTF-8, Latin-1 and ASCII.
20783 - Andy Stewart contributed code to =org-w3m.el=, to copy
20784 HTML content with links transformation to Org syntax.
20786 - David O'Toole wrote =org-publish.el= and drafted the
20787 manual chapter about publishing.
20789 - Jambunathan\nbsp{}K.\nbsp{}contributed the ODT exporter.
20791 - Sebastien Vauban reported many issues with LaTeX and Beamer export
20792 and enabled source code highlighting in Gnus.
20794 - Stefan Vollmar organized a video-recorded talk at the
20795 Max-Planck-Institute for Neurology. He also inspired the creation
20796 of a concept index for HTML export.
20798 - Jürgen Vollmer contributed code generating the table of contents in
20801 - Samuel Wales has provided important feedback and bug reports.
20803 - Chris Wallace provided a patch implementing the =QUOTE= block.
20805 - David Wainberg suggested archiving, and improvements to the
20808 - Carsten Wimmer suggested some changes and helped fix a bug in
20811 - Roland Winkler requested additional key bindings to make Org work on
20814 - Piotr Zielinski wrote =org-mouse.el=, proposed agenda
20815 blocks and contributed various ideas and code snippets.
20817 - Marco Wahl wrote =org-eww.el=.
20819 * GNU Free Documentation License
20822 :DESCRIPTION: The license for this documentation.
20825 #+texinfo: @include doclicense.texi
20830 :DESCRIPTION: An index of Org's concepts and features.
20835 :DESCRIPTION: Key bindings and where they are described.
20839 * Command and Function Index
20841 :DESCRIPTION: Command names and some internal functions.
20847 :DESCRIPTION: Variables mentioned in the manual.
20851 This is not a complete index of variables and faces, only the ones
20852 that are mentioned in the manual. For a more complete list, use
20853 {{{kbd(M-x org-customize)}}} and then click yourself through the tree.
20860 This manual is for Org version {{{version}}}.
20862 Copyright \copy 2004--2019 Free Software Foundation, Inc.
20865 Permission is granted to copy, distribute and/or modify this document
20866 under the terms of the GNU Free Documentation License, Version 1.3 or
20867 any later version published by the Free Software Foundation; with no
20868 Invariant Sections, with the Front-Cover Texts being "A GNU Manual,"
20869 and with the Back-Cover Texts as in (a) below. A copy of the license
20870 is included in the section entitled "GNU Free Documentation License."
20872 (a) The FSF's Back-Cover Text is: "You have the freedom to copy and
20873 modify this GNU manual."
20876 * Export Setup :noexport:
20878 #+subtitle: Release {{{version}}}
20879 #+author: The Org Mode Developers
20880 #+date: {{{modification-time}}}
20883 # XXX: We cannot use TODO keyword as a node starts with "TODO".
20884 #+todo: REVIEW FIXME | DONE
20885 #+property: header-args :eval no
20886 #+startup: overview nologdone
20888 #+export_file_name: org.texi
20890 #+texinfo_dir_category: Emacs editing modes
20891 #+texinfo_dir_title: Org Mode: (org)
20892 #+texinfo_dir_desc: Outline-based notes management and organizer
20894 # Use proper quote and backtick for code sections in PDF output
20895 # Cf. Texinfo manual 14.2
20896 #+texinfo_header: @set txicodequoteundirected
20897 #+texinfo_header: @set txicodequotebacktick
20900 #+texinfo_header: @set MAINTAINERSITE @uref{https://orgmode.org,maintainers webpage}
20901 #+texinfo_header: @set MAINTAINER Carsten Dominik
20902 #+texinfo_header: @set MAINTAINEREMAIL @email{carsten at orgmode dot org}
20903 #+texinfo_header: @set MAINTAINERCONTACT @uref{mailto:carsten at orgmode dot org,contact the maintainer}
20905 #+options: H:4 num:t toc:t author:t \n:nil ::t |:t ^:nil -:t f:t *:t <:t e:t ':t
20906 #+options: d:nil todo:nil pri:nil tags:not-in-toc stat:nil broken-links:mark
20907 #+select_tags: export
20908 #+exclude_tags: noexport
20910 #+macro: cite @@texinfo:@cite{@@$1@@texinfo:}@@
20911 #+macro: var @@texinfo:@var{@@$1@@texinfo:}@@
20913 # The "version" macro extracts "Version" keyword from "org.el". It
20914 # returns major.minor version number. This is sufficient since bugfix
20915 # releases are not expected to add features and therefore imply manual
20917 #+macro: version (eval (with-current-buffer (find-file-noselect "../lisp/org.el") (org-with-point-at 1 (if (re-search-forward "Version: +\\([0-9.]+\\)" nil t) (mapconcat #'identity (cl-subseq (split-string (match-string-no-properties 1) "\\.") 0 2) ".") (error "Missing \"Version\" keyword in \"org.el\"")))))
20919 # The "kbd" macro turns KBD into @kbd{KBD}. Additionnally, it
20920 # encloses case-sensitive special keys (SPC, RET...) within @key{...}.
20921 #+macro: kbd (eval (let ((case-fold-search nil) (regexp (regexp-opt '("SPC" "RET" "LFD" "TAB" "BS" "ESC" "DELETE" "SHIFT" "Ctrl" "Meta" "Alt" "Cmd" "Super" "UP" "LEFT" "RIGHT" "DOWN") 'words))) (format "@@texinfo:@kbd{@@%s@@texinfo:}@@" (replace-regexp-in-string regexp "@@texinfo:@key{@@\\&@@texinfo:}@@" $1 t))))
20925 [fn:1] If you do not use Font Lock globally turn it on in Org buffer
20926 with =(add-hook 'org-mode-hook 'turn-on-font-lock)=.
20928 [fn:2] Please consider subscribing to the mailing list in order to
20929 minimize the work the mailing list moderators have to do.
20931 [fn:3] See the variables ~org-special-ctrl-a/e~, ~org-special-ctrl-k~,
20932 and ~org-ctrl-k-protect-subtree~ to configure special behavior of
20933 {{{kbd(C-a)}}}, {{{kbd(C-e)}}}, and {{{kbd(C-k)}}} in headlines. Note
20934 also that clocking only works with headings indented less than 30
20937 [fn:4] See, however, the option ~org-cycle-emulate-tab~.
20939 [fn:5] The indirect buffer contains the entire buffer, but is narrowed
20940 to the current tree. Editing the indirect buffer also changes the
20941 original buffer, but without affecting visibility in that buffer. For
20942 more information about indirect buffers, see [[info:emacs#Indirect%20Buffers][GNU Emacs Manual]].
20944 [fn:6] When ~org-agenda-inhibit-startup~ is non-~nil~, Org does not
20945 honor the default visibility state when first opening a file for the
20946 agenda (see [[*Speeding Up Your Agendas]]).
20948 [fn:7] See also the variable ~org-show-context-detail~ to decide how
20949 much context is shown around each match.
20951 [fn:8] This depends on the option ~org-remove-highlights-with-change~.
20953 [fn:9] When using =*= as a bullet, lines must be indented so that they
20954 are not interpreted as headlines. Also, when you are hiding leading
20955 stars to get a clean outline view, plain list items starting with
20956 a star may be hard to distinguish from true headlines. In short: even
20957 though =*= is supported, it may be better to not use it for plain list
20960 [fn:10] You can filter out any of them by configuring
20961 ~org-plain-list-ordered-item-terminator~.
20963 [fn:11] You can also get =a.=, =A.=, =a)= and =A)= by configuring
20964 ~org-list-allow-alphabetical~. To minimize confusion with normal
20965 text, those are limited to one character only. Beyond that limit,
20966 bullets automatically become numbers.
20968 [fn:12] If there's a checkbox in the item, the cookie must be put
20969 /before/ the checkbox. If you have activated alphabetical lists, you
20970 can also use counters like =[@b]=.
20972 [fn:13] If you do not want the item to be split, customize the
20973 variable ~org-M-RET-may-split-line~.
20975 [fn:14] If you want to cycle around items that way, you may customize
20976 ~org-list-use-circular-motion~.
20978 [fn:15] See ~org-list-use-circular-motion~ for a cyclic behavior.
20980 [fn:16] Many desktops intercept {{{kbd(M-TAB)}}} to switch windows.
20981 Use {{{kbd(C-M-i)}}} or {{{kbd(ESC TAB)}}} instead.
20983 [fn:17] The corresponding in-buffer setting is: =#+STARTUP: fninline=
20984 or =#+STARTUP: nofninline=.
20986 [fn:18] The corresponding in-buffer options are =#+STARTUP: fnadjust=
20987 and =#+STARTUP: nofnadjust=.
20989 [fn:19] To insert a vertical bar into a table field, use =\vert= or,
20990 inside a word =abc\vert{}def=.
20992 [fn:20] Org understands references typed by the user as =B4=, but it
20993 does not use this syntax when offering a formula for editing. You can
20994 customize this behavior using the variable
20995 ~org-table-use-standard-references~.
20997 [fn:21] The computation time scales as O(N^2) because table
20998 {{{var(FOO)}}} is parsed for each field to be copied.
21000 [fn:22] The file =constants.el= can supply the values of constants in
21001 two different unit systems, =SI= and =cgs=. Which one is used depends
21002 on the value of the variable ~constants-unit-system~. You can use the
21003 =STARTUP= options =constSI= and =constcgs= to set this value for the
21006 [fn:23] The printf reformatting is limited in precision because the
21007 value passed to it is converted into an "integer" or "double". The
21008 "integer" is limited in size by truncating the signed value to 32
21009 bits. The "double" is limited in precision to 64 bits overall which
21010 leaves approximately 16 significant decimal digits.
21012 [fn:24] Such names must start with an alphabetic character and use
21013 only alphanumeric/underscore characters.
21015 [fn:25] Plain URIs are recognized only for a well-defined set of
21016 schemes. See [[*External Links]]. Unlike URI syntax, they cannot contain
21017 parenthesis or white spaces, either. URIs within angle brackets have
21018 no such limitation.
21020 [fn:26] More accurately, the precise behavior depends on how point
21021 arrived there---see [[info:elisp#Invisible%20Text][Invisible Text]].
21023 [fn:27] To insert a link targeting a headline, in-buffer completion
21024 can be used. Just type a star followed by a few optional letters into
21025 the buffer and press {{{kbd(M-TAB)}}}. All headlines in the current
21026 buffer are offered as completions.
21028 [fn:28] When targeting a =NAME= keyword, the =CAPTION= keyword is
21029 mandatory in order to get proper numbering (see [[*Captions]]).
21031 [fn:29] The actual behavior of the search depends on the value of the
21032 variable ~org-link-search-must-match-exact-headline~. If its value is
21033 ~nil~, then a fuzzy text search is done. If it is ~t~, then only the
21034 exact headline is matched, ignoring spaces and statistic cookies. If
21035 the value is ~query-to-create~, then an exact headline is searched; if
21036 it is not found, then the user is queried to create it.
21038 [fn:30] If the headline contains a timestamp, it is removed from the
21039 link, which results in a wrong link---you should avoid putting
21040 a timestamp in the headline.
21042 [fn:31] The Org Id library must first be loaded, either through
21043 ~org-customize~, by enabling ~id~ in ~org-modules~, or by adding
21044 =(require 'org-id)= in your Emacs init file.
21046 [fn:32] Note that you do not have to use this command to insert
21047 a link. Links in Org are plain text, and you can type or paste them
21048 straight into the buffer. By using this command, the links are
21049 automatically enclosed in double brackets, and you will be asked for
21050 the optional descriptive text.
21052 [fn:33] After insertion of a stored link, the link will be removed
21053 from the list of stored links. To keep it in the list for later use,
21054 use a triple {{{kbd(C-u)}}} prefix argument to {{{kbd(C-c C-l)}}}, or
21055 configure the option ~org-keep-stored-link-after-insertion~.
21057 [fn:34] This works if a function has been defined in the ~:complete~
21058 property of a link in ~org-link-parameters~.
21060 [fn:35] See the variable ~org-display-internal-link-with-indirect-buffer~.
21062 [fn:36] For backward compatibility, line numbers can also follow a
21065 [fn:37] Of course, you can make a document that contains only long
21066 lists of TODO items, but this is not required.
21068 [fn:38] Changing the variable ~org-todo-keywords~ only becomes
21069 effective after restarting Org mode in a buffer.
21071 [fn:39] This is also true for the {{{kbd(t)}}} command in the agenda
21074 [fn:40] All characters are allowed except =@=, =^= and =!=, which have
21075 a special meaning here.
21077 [fn:41] Check also the variable ~org-fast-tag-selection-include-todo~,
21078 it allows you to change the TODO state through the tags interface (see
21079 [[*Setting Tags]]), in case you like to mingle the two concepts. Note
21080 that this means you need to come up with unique keys across both sets
21083 [fn:42] Org mode parses these lines only when Org mode is activated
21084 after visiting a file. {{{kbd(C-c C-c)}}} with point in a line
21085 starting with =#+= is simply restarting Org mode for the current
21088 [fn:43] The corresponding in-buffer setting is: =#+STARTUP: logdone=.
21090 [fn:44] The corresponding in-buffer setting is: =#+STARTUP:
21093 [fn:45] See the variable ~org-log-states-order-reversed~.
21095 [fn:46] Note that the =LOGBOOK= drawer is unfolded when pressing
21096 {{{kbd(SPC)}}} in the agenda to show an entry---use {{{kbd(C-u
21097 SPC)}}} to keep it folded here.
21099 [fn:47] It is possible that Org mode records two timestamps when you
21100 are using both ~org-log-done~ and state change logging. However, it
21101 never prompts for two notes: if you have configured both, the state
21102 change recording note takes precedence and cancel the closing note.
21104 [fn:48] See also the option ~org-priority-start-cycle-with-default~.
21106 [fn:49] To keep subtasks out of the global TODO list, see the option
21107 ~org-agenda-todo-list-sublevels~.
21109 [fn:50] With the exception of description lists. But you can allow it
21110 by modifying ~org-list-automatic-rules~ accordingly.
21112 [fn:51] Set the variable ~org-hierarchical-checkbox-statistics~ if you
21113 want such cookies to count all checkboxes below the cookie, not just
21114 those belonging to direct children.
21116 [fn:52] {{{kbd(C-u C-c C-c)}}} on the /first/ item of a list with no
21117 checkbox adds checkboxes to the rest of the list.
21119 [fn:53] As with all these in-buffer settings, pressing {{{kbd(C-c
21120 C-c)}}} activates any changes in the line.
21122 [fn:54] This is only true if the search does not involve more complex
21123 tests including properties (see [[*Property Searches]]).
21125 [fn:55] To extend this default list to all tags used in all agenda
21126 files (see [[*Agenda Views]]), customize the variable
21127 ~org-complete-tags-always-offer-all-agenda-tags~.
21129 [fn:56] Keys are automatically assigned to tags that have no
21132 [fn:57] If more than one summary type applies to the same property,
21133 the parent values are computed according to the first of them.
21135 [fn:58] An age can be defined as a duration, using units defined in
21136 ~org-duration-units~, e.g., =3d 1h=. If any value in the column is as
21137 such, the summary is also expressed as a duration.
21139 [fn:59] Please note that the =COLUMNS= definition must be on a single
21140 line; it is wrapped here only because of formatting constraints.
21142 [fn:60] Contributed packages are not part of Emacs, but are
21143 distributed with the main distribution of Org---visit
21144 [[https://orgmode.org]].
21146 [fn:61] The Org date format is inspired by the standard ISO 8601
21147 date/time format. To use an alternative format, see [[*Custom time
21148 format]]. The day name is optional when you type the date yourself.
21149 However, any date inserted or modified by Org adds that day name, for
21150 reading convenience.
21152 [fn:62] When working with the standard diary sexp functions, you need
21153 to be very careful with the order of the arguments. That order
21154 depends evilly on the variable ~calendar-date-style~. For example, to
21155 specify a date December 12, 2005, the call might look like
21156 =(diary-date 12 1 2005)= or =(diary-date 1 12 2005)= or =(diary-date
21157 2005 12 1)=, depending on the settings. This has been the source of
21158 much confusion. Org mode users can resort to special versions of
21159 these functions like ~org-date~ or ~org-anniversary~. These work just
21160 like the corresponding ~diary-~ functions, but with stable ISO order
21161 of arguments (year, month, day) wherever applicable, independent of
21162 the value of ~calendar-date-style~.
21164 [fn:63] See the variable ~org-read-date-prefer-future~. You may set
21165 that variable to the symbol ~time~ to even make a time before now
21166 shift the date to tomorrow.
21168 [fn:64] If you do not need/want the calendar, configure the variable
21169 ~org-popup-calendar-for-date-prompt~.
21171 [fn:65] If you find this distracting, turn off the display with
21172 ~org-read-date-display-live~.
21174 [fn:66] It will still be listed on that date after it has been marked
21175 DONE. If you do not like this, set the variable
21176 ~org-agenda-skip-scheduled-if-done~.
21178 [fn:67] The =SCHEDULED= and =DEADLINE= dates are inserted on the line
21179 right below the headline. Do not put any text between this line and
21182 [fn:68] Note the corresponding =STARTUP= options =logredeadline=,
21183 =lognoteredeadline=, and =nologredeadline=.
21185 [fn:69] Note the corresponding =STARTUP= options =logreschedule=,
21186 =lognotereschedule=, and =nologreschedule=.
21188 [fn:70] Org does not repeat inactive timestamps, however. See
21189 [[*Timestamps, Deadlines and Scheduling]].
21191 [fn:71] In fact, the target state is taken from, in this sequence, the
21192 =REPEAT_TO_STATE= property, the variable ~org-todo-repeat-to-state~ if
21193 it is a string, the previous TODO state if ~org-todo-repeat-to-state~
21194 is ~t~, or the first state of the TODO state sequence.
21196 [fn:72] You can change this using the option ~org-log-repeat~, or the
21197 =STARTUP= options =logrepeat=, =lognoterepeat=, and =nologrepeat=.
21198 With =lognoterepeat=, you will also be prompted for a note.
21200 [fn:73] Clocking only works if all headings are indented with less
21201 than 30 stars. This is a hard-coded limitation of ~lmax~ in
21204 [fn:74] To resume the clock under the assumption that you have worked
21205 on this task while outside Emacs, use =(setq org-clock-persist t)=.
21207 [fn:75] To add an effort estimate "on the fly", hook a function doing
21208 this to ~org-clock-in-prepare-hook~.
21210 [fn:76] The last reset of the task is recorded by the =LAST_REPEAT=
21213 [fn:77] See also the variable ~org-clock-mode-line-total~.
21215 [fn:78] The corresponding in-buffer setting is: =#+STARTUP:
21218 [fn:79] When using ~:step~, ~untilnow~ starts from the beginning of
21219 2003, not the beginning of time.
21221 [fn:80] Language terms can be set through the variable
21222 ~org-clock-clocktable-language-setup~.
21224 [fn:81] Note that all parameters must be specified in a single
21225 line---the line is broken here only to fit it into the manual.
21227 [fn:82] On computers using macOS, idleness is based on actual user
21228 idleness, not just Emacs' idle time. For X11, you can install
21229 a utility program =x11idle.c=, available in the =contrib/scripts/=
21230 directory of the Org Git distribution, or install the xprintidle
21231 package and set it to the variable ~org-clock-x11idle-program-name~ if
21232 you are running Debian, to get the same general treatment of idleness.
21233 On other systems, idle time refers to Emacs idle time only.
21235 [fn:83] Please note the pitfalls of summing hierarchical data in
21236 a flat list (see [[*Using Column View in the Agenda]]).
21238 [fn:84] Org used to offer four different targets for date/week tree
21239 capture. Now, Org automatically translates these to use
21240 ~file+olp+datetree~, applying the ~:time-prompt~ and ~:tree-type~
21241 properties. Please rewrite your date/week-tree targets using
21242 ~file+olp+datetree~ since the older targets are now deprecated.
21244 [fn:85] A date tree is an outline structure with years on the highest
21245 level, months or ISO weeks as sublevels and then dates on the lowest
21246 level. Tags are allowed in the tree structure.
21248 [fn:86] If you need one of these sequences literally, escape the =%=
21251 [fn:87] If you define your own link types (see [[*Adding Hyperlink
21252 Types]]), any property you store with ~org-store-link-props~ can be
21253 accessed in capture templates in a similar way.
21255 [fn:88] This is always the other, not the user. See the variable
21256 ~org-from-is-user-regexp~.
21258 [fn:89] If you move entries or Org files from one directory to
21259 another, you may want to configure ~org-attach-directory~ to contain
21262 [fn:90] Note the corresponding =STARTUP= options =logrefile=,
21263 =lognoterefile=, and =nologrefile=.
21265 [fn:91] If the value of that variable is not a list, but a single file
21266 name, then the list of agenda files in maintained in that external
21269 [fn:92] When using the dispatcher, pressing {{{kbd(<)}}} before
21270 selecting a command actually limits the command to the current file,
21271 and ignores ~org-agenda-files~ until the next dispatcher command.
21273 [fn:93] For backward compatibility, you can also press {{{kbd(1)}}} to
21274 restrict to the current buffer.
21276 [fn:94] For backward compatibility, you can also press {{{kbd(0)}}} to
21277 restrict to the current region/subtree.
21279 [fn:95] For backward compatibility, the universal prefix argument
21280 {{{kbd(C-u)}}} causes all TODO entries to be listed before the agenda.
21281 This feature is deprecated, use the dedicated TODO list, or a block
21282 agenda instead (see [[*Block agenda]]).
21284 [fn:96] The variable ~org-anniversary~ used in the example is just
21285 like ~diary-anniversary~, but the argument order is always according
21286 to ISO and therefore independent of the value of
21287 ~calendar-date-style~.
21289 [fn:97] You can, however, disable this by setting
21290 ~org-agenda-search-headline-for-time~ variable to a ~nil~ value.
21292 [fn:98] Custom commands can preset a filter by binding the variable
21293 ~org-agenda-tag-filter-preset~ as an option. This filter is then
21294 applied to the view and persists as a basic filter through refreshes
21295 and more secondary filtering. The filter is a global property of the
21296 entire agenda view---in a block agenda, you should only set this in
21297 the global options section, not in the section of an individual block.
21299 [fn:99] Only tags filtering is respected here, effort filtering is
21302 [fn:100] You can also create persistent custom functions through
21303 ~org-agenda-bulk-custom-functions~.
21305 [fn:101] This file is parsed for the agenda when
21306 ~org-agenda-include-diary~ is set.
21308 [fn:102] You can provide a description for a prefix key by inserting
21309 a cons cell with the prefix and the description.
21311 [fn:103] /Planned/ means here that these entries have some planning
21312 information attached to them, like a time-stamp, a scheduled or
21313 a deadline string. See ~org-agenda-entry-types~ on how to set what
21314 planning information is taken into account.
21316 [fn:104] For HTML you need to install Hrvoje Niksic's =htmlize.el=
21317 from [[https://github.com/hniksic/emacs-htmlize][Hrvoje Niksic's repository]].
21319 [fn:105] To create PDF output, the Ghostscript ps2pdf utility must be
21320 installed on the system. Selecting a PDF file also creates the
21323 [fn:106] If you want to store standard views like the weekly agenda or
21324 the global TODO list as well, you need to define custom commands for
21325 them in order to be able to specify file names.
21327 [fn:107] Quoting depends on the system you use, please check the FAQ
21330 [fn:108] You can turn this on by default by setting the variable
21331 ~org-pretty-entities~, or on a per-file base with the =STARTUP= option
21334 [fn:109] This behavior can be disabled with =-= export setting (see
21335 [[*Export Settings]]).
21337 [fn:110] LaTeX is a macro system based on Donald\nbsp{}E.\nbsp{}Knuth's TeX
21338 system. Many of the features described here as "LaTeX" are really
21339 from TeX, but for simplicity I am blurring this distinction.
21341 [fn:111] When MathJax is used, only the environments recognized by
21342 MathJax are processed. When dvipng, dvisvgm, or ImageMagick suite is
21343 used to create images, any LaTeX environment is handled.
21345 [fn:112] These are respectively available at
21346 [[http://sourceforge.net/projects/dvipng/]], [[http://dvisvgm.bplaced.net/]]
21347 and from the ImageMagick suite. Choose the converter by setting the
21348 variable ~org-preview-latex-default-process~ accordingly.
21350 [fn:113] Org mode has a method to test if point is inside such
21351 a fragment, see the documentation of the function
21352 ~org-inside-LaTeX-fragment-p~.
21354 [fn:114] This works automatically for the HTML backend (it requires
21355 version 1.34 of the =htmlize.el= package, which you need to install).
21356 Fontified code chunks in LaTeX can be achieved using either the
21357 [[https://www.ctan.org/pkg/listings][listings]] package or the [[https://www.ctan.org/pkg/minted][minted]] package. Refer to
21358 ~org-export-latex-listings~ for details.
21360 [fn:115] Source code in code blocks may also be evaluated either
21361 interactively or on export. See [[*Working with Source Code]] for more
21362 information on evaluating code blocks.
21364 [fn:116] Adding =-k= to =-n -r= /keeps/ the labels in the source code
21365 while using line numbers for the links, which might be useful to
21366 explain those in an Org mode example code.
21368 [fn:117] Upon exit, lines starting with =*=, =,*=, =#+= and =,#+= get
21369 a comma prepended, to keep them from being interpreted by Org as
21370 outline nodes or special syntax. These commas are stripped when
21371 editing with {{{kbd(C-c ')}}}, and also before export.
21373 [fn:118] You may select a different-mode with the variable
21374 ~org-edit-fixed-width-region-mode~.
21376 [fn:119] What Emacs considers to be an image depends on
21377 ~image-file-name-extensions~ and ~image-file-name-regexps~.
21379 [fn:120] The variable ~org-startup-with-inline-images~ can be set
21380 within a buffer with the =STARTUP= options =inlineimages= and
21383 [fn:121] The variable ~org-export-date-timestamp-format~ defines how
21384 this timestamp are exported.
21386 [fn:122] For export to LaTeX format---or LaTeX-related formats such as
21387 Beamer---, the =org-latex-package-alist= variable needs further
21388 configuration. See [[LaTeX specific export settings]].
21390 [fn:123] At the moment, some export back-ends do not obey this
21391 specification. For example, LaTeX export excludes every unnumbered
21392 headline from the table of contents.
21394 [fn:124] Note that ~org-link-search-must-match-exact-headline~ is
21395 locally bound to non-~nil~. Therefore, ~org-link-search~ only matches
21396 headlines and named elements.
21398 [fn:125] Since commas separate the arguments, commas within arguments
21399 have to be escaped with the backslash character. So only those
21400 backslash characters before a comma need escaping with another
21401 backslash character.
21403 [fn:126] For a less drastic behavior, consider using a select tag (see
21404 [[*Export Settings]]) instead.
21406 [fn:127] If =BEAMER_ENV= is set, Org export adds =B_environment= tag
21407 to make it visible. The tag serves as a visual aid and has no
21408 semantic relevance.
21410 [fn:128] By default Org loads MathJax from [[https://cdnjs.com][cdnjs.com]] as recommended by
21411 [[http://www.mathjax.org][MathJax]].
21413 [fn:129] Please note that exported formulas are part of an HTML
21414 document, and that signs such as =<=, =>=, or =&= have special
21415 meanings. See [[http://docs.mathjax.org/en/latest/tex.html#tex-and-latex-in-html-documents][MathJax TeX and LaTeX support]].
21417 [fn:130] See [[http://docs.mathjax.org/en/latest/tex.html#tex-extensions][TeX and LaTeX extensions]] in the [[http://docs.mathjax.org][MathJax manual]] to learn
21420 [fn:131] If the classes on TODO keywords and tags lead to conflicts,
21421 use the variables ~org-html-todo-kwd-class-prefix~ and
21422 ~org-html-tag-class-prefix~ to make them unique.
21424 [fn:132] This does not allow setting different bibliography compilers
21425 for different files. However, "smart" LaTeX compilation systems, such
21426 as latexmk, can select the correct bibliography compiler.
21428 [fn:133] See [[http://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2.html][Open Document Format for Office Applications
21429 (OpenDocument) Version 1.2]].
21431 [fn:134] See [[http://www.mathtoweb.com/cgi-bin/mathtoweb_home.pl][MathToWeb]].
21433 [fn:135] See [[http://dlmf.nist.gov/LaTeXML/]].
21435 [fn:136] [[http://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2.html][OpenDocument-v1.2 Specification]]
21437 [fn:137] See the =<table:table-template>= element of the
21438 OpenDocument-v1.2 specification.
21440 [fn:138] See the attributes =table:template-name=,
21441 =table:use-first-row-styles=, =table:use-last-row-styles=,
21442 =table:use-first-column-styles=, =table:use-last-column-styles=,
21443 =table:use-banding-rows-styles=, and =table:use-banding-column-styles=
21444 of the =<table:table>= element in the OpenDocument-v1.2 specification.
21446 [fn:139] If the publishing directory is the same as the source
21447 directory, =file.org= is exported as =file.org.org=, so you probably
21448 do not want to do this.
21450 [fn:140] The option ~org-babel-no-eval-on-ctrl-c-ctrl-c~ can be used
21451 to remove code evaluation from the {{{kbd(C-c C-c)}}} key binding.
21453 [fn:141] Actually, the constructs =call_<name>()= and =src_<lang>{}=
21454 are not evaluated when they appear in a keyword (see [[*Summary of
21455 In-Buffer Settings]]).
21457 [fn:142] Due to the way this header argument is implemented, it
21458 implies ":results file". Therefore if it is set for multiple blocks
21459 at once (by a subtree or buffer property for example), all blocks are
21460 forced to produce file results. This is seldom desired behavior, so
21461 it is recommended to set this header only on a per-block basis. It is
21462 possible that this aspect of the implementation might change in the
21465 [fn:143] C++ language is handled in =ob-C.el=. Even though the
21466 identifier for such source blocks is =C++=, you activate it by loading
21469 [fn:144] D language is handled in =ob-C.el=. Even though the
21470 identifier for such source blocks is =D=, you activate it by loading
21473 [fn:145] For Noweb literate programming details, see
21474 http://www.cs.tufts.edu/~nr/noweb/.
21476 [fn:146] For more information, please refer to the commentary section
21479 [fn:147] Note that ~org-indent-mode~ also sets the ~wrap-prefix~
21480 property, such that ~visual-line-mode~ (or purely setting ~word-wrap~)
21481 wraps long lines (including headlines) correctly indented.
21483 [fn:148] The ~org-indent-mode~ also sets the ~wrap-prefix~ correctly
21484 for indenting and wrapping long lines of headlines or text. This
21485 minor mode handles ~visual-line-mode~ and directly applied settings
21486 through ~word-wrap~.
21488 [fn:149] Also see the variable ~org-adapt-indentation~.
21490 [fn:150] Because =LEVEL=2= has 3 stars, =LEVEL=3= has 4 stars, and so
21493 [fn:151] For a server to host files, consider using a WebDAV server,
21494 such as [[https://nextcloud.com][Nextcloud]]. Additional help is at this [[https://orgmode.org/worg/org-faq.html#mobileorg_webdav][FAQ entry]].
21496 [fn:152] If Emacs is configured for safe storing of passwords, then
21497 configure the variable ~org-mobile-encryption-password~; please read
21498 the docstring of that variable.
21500 [fn:153] Symbolic links in ~org-directory~ need to have the same name
21503 [fn:154] While creating the agendas, Org mode forces =ID= properties
21504 on all referenced entries, so that these entries can be uniquely
21505 identified if Org Mobile flags them for further action. To avoid
21506 setting properties configure the variable
21507 ~org-mobile-force-id-on-agenda-items~ to ~nil~. Org mode then relies
21508 on outline paths, assuming they are unique.
21510 [fn:155] Checksums are stored automatically in the file
21513 [fn:156] The file will be empty after this operation.
21515 [fn:157] https://www.ctan.org/pkg/comment
21517 [fn:158] If the =TBLFM= keyword contains an odd number of dollar
21518 characters, this may cause problems with Font Lock in LaTeX mode. As
21519 shown in the example you can fix this by adding an extra line inside
21520 the =comment= environment that is used to balance the dollar
21521 expressions. If you are using AUCTeX with the font-latex library,
21522 a much better solution is to add the =comment= environment to the
21523 variable ~LaTeX-verbatim-environments~.
21525 [fn:159] The ~agenda*~ view is the same as ~agenda~ except that it
21526 only considers /appointments/, i.e., scheduled and deadline items that
21527 have a time specification =[h]h:mm= in their time-stamps.
21529 [fn:160] Note that, for ~org-odd-levels-only~, a level number
21530 corresponds to order in the hierarchy, not to the number of stars.