3 @setfilename ../../info/orgguide
4 @settitle The compact Org-mode Guide
9 @c Use proper quote and backtick for code sections in PDF output
10 @c Cf. Texinfo manual 14.2
11 @set txicodequoteundirected
12 @set txicodequotebacktick
14 @c Version and Contact Info
15 @set MAINTAINERSITE @uref{http://orgmode.org,maintainers webpage}
16 @set AUTHOR Carsten Dominik
17 @set MAINTAINER Carsten Dominik
18 @set MAINTAINEREMAIL @email{carsten at orgmode dot org}
19 @set MAINTAINERCONTACT @uref{mailto:carsten at orgmode dot org,contact the maintainer}
25 @c @hyphenation{time-stamp time-stamps time-stamp-ing time-stamp-ed}
28 @c Subheadings inside a table.
29 @macro tsubheading{text}
39 @noindent @b{Further reading}@*@noindent \text\
43 Copyright @copyright{} 2010-2012 Free Software Foundation
46 Permission is granted to copy, distribute and/or modify this document
47 under the terms of the GNU Free Documentation License, Version 1.3 or
48 any later version published by the Free Software Foundation; with no
49 Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
50 and with the Back-Cover Texts as in (a) below. A copy of the license
51 is included in the section entitled ``GNU Free Documentation License.''
53 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
54 modify this GNU manual. Buying copies from the FSF supports it in
55 developing GNU and promoting software freedom.''
57 This document is part of a collection distributed under the GNU Free
58 Documentation License. If you want to distribute this document
59 separately from the collection, you can do so by adding a copy of the
60 license to the document, as described in section 6 of the license.
66 * Org Mode Guide: (orgguide). Abbreviated Org-mode Manual
70 @title The compact Org-mode Guide
72 @subtitle Release @value{VERSION}
73 @author by Carsten Dominik
75 @c The following two commands start the copyright page.
77 @vskip 0pt plus 1filll
81 @c Output the table of contents at the beginning.
85 @node Top, Introduction, (dir), (dir)
92 * Introduction:: Getting started
93 * Document Structure:: A tree works like your brain
94 * Tables:: Pure magic for quick formatting
95 * Hyperlinks:: Notes in context
96 * TODO Items:: Every tree branch can be a TODO item
97 * Tags:: Tagging headlines and matching sets of tags
98 * Properties:: Properties
99 * Dates and Times:: Making items useful for planning
100 * Capture - Refile - Archive:: The ins and outs for projects
101 * Agenda Views:: Collecting information into views
102 * Markup:: Prepare text for rich export
103 * Exporting:: Sharing and publishing of notes
104 * Publishing:: Create a web site of linked Org files
105 * Working With Source Code:: Source code snippets embedded in Org
106 * Miscellaneous:: All the rest which did not fit elsewhere
109 --- The Detailed Node Listing ---
114 * Installation:: How to install a downloaded version of Org
115 * Activation:: How to activate Org for certain buffers
116 * Feedback:: Bug reports, ideas, patches etc.
120 * Outlines:: Org is based on Outline mode
121 * Headlines:: How to typeset Org tree headlines
122 * Visibility cycling:: Show and hide, much simplified
123 * Motion:: Jumping to other headlines
124 * Structure editing:: Changing sequence and level of headlines
125 * Sparse trees:: Matches embedded in context
126 * Plain lists:: Additional structure within an entry
127 * Footnotes:: How footnotes are defined in Org's syntax
131 * Link format:: How links in Org are formatted
132 * Internal links:: Links to other places in the current file
133 * External links:: URL-like links to the world
134 * Handling links:: Creating, inserting and following
135 * Targeted links:: Point at a location in a file
139 * Using TODO states:: Setting and switching states
140 * Multi-state workflows:: More than just on/off
141 * Progress logging:: Dates and notes for progress
142 * Priorities:: Some things are more important than others
143 * Breaking down tasks:: Splitting a task into manageable pieces
144 * Checkboxes:: Tick-off lists
148 * Closing items:: When was this entry marked DONE?
149 * Tracking TODO state changes:: When did the status change?
153 * Tag inheritance:: Tags use the tree structure of the outline
154 * Setting tags:: How to assign tags to a headline
155 * Tag searches:: Searching for combinations of tags
159 * Timestamps:: Assigning a time to a tree entry
160 * Creating timestamps:: Commands which insert timestamps
161 * Deadlines and scheduling:: Planning your work
162 * Clocking work time:: Tracking how long you spend on a task
164 Capture - Refile - Archive
167 * Refiling notes:: Moving a tree from one place to another
168 * Archiving:: What to do with finished projects
172 * Setting up a capture location:: Where notes will be stored
173 * Using capture:: Commands to invoke and terminate capture
174 * Capture templates:: Define the outline of different note types
178 * Agenda files:: Files being searched for agenda information
179 * Agenda dispatcher:: Keyboard access to agenda views
180 * Built-in agenda views:: What is available out of the box?
181 * Agenda commands:: Remote editing of Org trees
182 * Custom agenda views:: Defining special searches and views
184 The built-in agenda views
186 * Weekly/daily agenda:: The calendar page with current tasks
187 * Global TODO list:: All unfinished action items
188 * Matching tags and properties:: Structured information with fine-tuned search
189 * Timeline:: Time-sorted view for single file
190 * Search view:: Find entries by searching for text
192 Markup for rich export
194 * Structural markup elements:: The basic structure as seen by the exporter
195 * Images and tables:: Tables and Images will be included
196 * Literal examples:: Source code examples with special formatting
197 * Include files:: Include additional files into a document
198 * Embedded @LaTeX{}:: @LaTeX{} can be freely used inside Org documents
200 Structural markup elements
202 * Document title:: Where the title is taken from
203 * Headings and sections:: The document structure as seen by the exporter
204 * Table of contents:: The if and where of the table of contents
205 * Paragraphs:: Paragraphs
206 * Emphasis and monospace:: Bold, italic, etc.
207 * Comment lines:: What will *not* be exported
211 * Export options:: Per-file export settings
212 * The export dispatcher:: How to access exporter commands
213 * ASCII/Latin-1/UTF-8 export:: Exporting to flat files with encoding
214 * HTML export:: Exporting to HTML
215 * @LaTeX{} and PDF export:: Exporting to @LaTeX{}, and processing to PDF
216 * DocBook export:: Exporting to DocBook
221 * Completion:: M-TAB knows what you need
222 * Clean view:: Getting rid of leading stars in the outline
223 * MobileOrg:: Org-mode on the iPhone
228 @node Introduction, Document Structure, Top, Top
229 @chapter Introduction
233 * Installation:: How to install a downloaded version of Org
234 * Activation:: How to activate Org for certain buffers
235 * Feedback:: Bug reports, ideas, patches etc.
238 @node Preface, Installation, Introduction, Introduction
241 Org is a mode for keeping notes, maintaining TODO lists, and doing project
242 planning with a fast and effective plain-text system. It is also an
243 authoring and publishing system.
245 @i{This document is a much compressed derivative of the
246 @uref{http://orgmode.org/index.html#sec-4_1, comprehensive Org-mode manual}.
247 It contains all basic features and commands, along with important hints for
248 customization. It is intended for beginners who would shy back from a 200
249 page manual because of sheer size.}
251 @node Installation, Activation, Preface, Introduction
252 @section Installation
254 @b{Important:} @i{If you are using a version of Org that is part of the Emacs
255 distribution or an XEmacs package, please skip this section and go directly
256 to @ref{Activation}.}
258 If you have downloaded Org from the Web, either as a distribution @file{.zip}
259 or @file{.tar} file, or as a Git archive, it is best to run it directly from
260 the distribution directory. You need to add the @file{lisp} subdirectories
261 to the Emacs load path. To do this, add the following line to @file{.emacs}:
264 (setq load-path (cons "~/path/to/orgdir/lisp" load-path))
265 (setq load-path (cons "~/path/to/orgdir/contrib/lisp" load-path))
268 @noindent For speed you should byte-compile the Lisp files with the shell
275 Then add the following line to @file{.emacs}. It is needed so that
276 Emacs can autoload functions that are located in files not immediately loaded
277 when Org-mode starts.
279 (require 'org-install)
282 @node Activation, Feedback, Installation, Introduction
285 Add the following lines to your @file{.emacs} file. The last three lines
286 define @emph{global} keys for some commands --- please choose suitable keys
290 ;; The following lines are always needed. Choose your own keys.
291 (add-to-list 'auto-mode-alist '("\\.org\\'" . org-mode))
292 (add-hook 'org-mode-hook 'turn-on-font-lock) ; not needed when global-font-lock-mode is on
293 (global-set-key "\C-cl" 'org-store-link)
294 (global-set-key "\C-ca" 'org-agenda)
295 (global-set-key "\C-cb" 'org-iswitchb)
298 With this setup, all files with extension @samp{.org} will be put
301 @node Feedback, , Activation, Introduction
304 If you find problems with Org, or if you have questions, remarks, or ideas
305 about it, please mail to the Org mailing list @email{emacs-orgmode@@gnu.org}.
306 For information on how to submit bug reports, see the main manual.
308 @node Document Structure, Tables, Introduction, Top
309 @chapter Document Structure
311 Org is based on Outline mode and provides flexible commands to
312 edit the structure of the document.
315 * Outlines:: Org is based on Outline mode
316 * Headlines:: How to typeset Org tree headlines
317 * Visibility cycling:: Show and hide, much simplified
318 * Motion:: Jumping to other headlines
319 * Structure editing:: Changing sequence and level of headlines
320 * Sparse trees:: Matches embedded in context
321 * Plain lists:: Additional structure within an entry
322 * Footnotes:: How footnotes are defined in Org's syntax
325 @node Outlines, Headlines, Document Structure, Document Structure
328 Org is implemented on top of Outline mode. Outlines allow a
329 document to be organized in a hierarchical structure, which (at least
330 for me) is the best representation of notes and thoughts. An overview
331 of this structure is achieved by folding (hiding) large parts of the
332 document to show only the general document structure and the parts
333 currently being worked on. Org greatly simplifies the use of
334 outlines by compressing the entire show/hide functionality into a single
335 command, @command{org-cycle}, which is bound to the @key{TAB} key.
337 @node Headlines, Visibility cycling, Outlines, Document Structure
340 Headlines define the structure of an outline tree. The headlines in
341 Org start with one or more stars, on the left margin@footnote{See
342 the variable @code{org-special-ctrl-a/e} to configure special behavior
343 of @kbd{C-a} and @kbd{C-e} in headlines.}. For example:
353 * Another top level headline
356 @noindent Some people find the many stars too noisy and would prefer an
357 outline that has whitespace followed by a single star as headline
358 starters. @ref{Clean view}, describes a setup to realize this.
360 @node Visibility cycling, Motion, Headlines, Document Structure
361 @section Visibility cycling
363 Outlines make it possible to hide parts of the text in the buffer.
364 Org uses just two commands, bound to @key{TAB} and
365 @kbd{S-@key{TAB}} to change the visibility in the buffer.
369 @emph{Subtree cycling}: Rotate current subtree among the states
372 ,-> FOLDED -> CHILDREN -> SUBTREE --.
373 '-----------------------------------'
376 When called with a prefix argument (@kbd{C-u @key{TAB}}) or with the shift
377 key, global cycling is invoked.
379 @item S-@key{TAB} @r{and} C-u @key{TAB}
380 @emph{Global cycling}: Rotate the entire buffer among the states
383 ,-> OVERVIEW -> CONTENTS -> SHOW ALL --.
384 '--------------------------------------'
387 @item C-u C-u C-u @key{TAB}
388 Show all, including drawers.
391 When Emacs first visits an Org file, the global state is set to
392 OVERVIEW, i.e.@: only the top level headlines are visible. This can be
393 configured through the variable @code{org-startup-folded}, or on a
394 per-file basis by adding a startup keyword @code{overview}, @code{content},
395 @code{showall}, like this:
402 @node Motion, Structure editing, Visibility cycling, Document Structure
404 The following commands jump to other headlines in the buffer.
412 Next heading same level.
414 Previous heading same level.
416 Backward to higher level heading.
419 @node Structure editing, Sparse trees, Motion, Document Structure
420 @section Structure editing
424 Insert new heading with same level as current. If the cursor is in a plain
425 list item, a new item is created (@pxref{Plain lists}). When this command is
426 used in the middle of a line, the line is split and the rest of the line
427 becomes the new headline@footnote{If you do not want the line to be split,
428 customize the variable @code{org-M-RET-may-split-line}.}.
430 Insert new TODO entry with same level as current heading.
431 @item @key{TAB} @r{in new, empty entry}
432 In a new entry with no text yet, @key{TAB} will cycle through reasonable
434 @item M-@key{left}@r{/}@key{right}
435 Promote/demote current heading by one level.
436 @item M-S-@key{left}@r{/}@key{right}
437 Promote/demote the current subtree by one level.
438 @item M-S-@key{up}@r{/}@key{down}
439 Move subtree up/down (swap with previous/next subtree of same
442 Refile entry or region to a different location. @xref{Refiling notes}.
444 Narrow buffer to current subtree / widen it again
447 When there is an active region (Transient Mark mode), promotion and
448 demotion work on all headlines in the region.
450 @node Sparse trees, Plain lists, Structure editing, Document Structure
451 @section Sparse trees
453 An important feature of Org mode is the ability to construct @emph{sparse
454 trees} for selected information in an outline tree, so that the entire
455 document is folded as much as possible, but the selected information is made
456 visible along with the headline structure above it@footnote{See also the
457 variables @code{org-show-hierarchy-above}, @code{org-show-following-heading},
458 @code{org-show-siblings}, and @code{org-show-entry-below} for detailed
459 control on how much context is shown around each match.}. Just try it out
460 and you will see immediately how it works.
462 Org mode contains several commands creating such trees, all these
463 commands can be accessed through a dispatcher:
467 This prompts for an extra key to select a sparse-tree creating command.
469 Occur. Prompts for a regexp and shows a sparse tree with all matches. Each
470 match is also highlighted; the highlights disappear by pressing @kbd{C-c C-c}.
473 The other sparse tree commands select headings based on TODO keywords,
474 tags, or properties and will be discussed later in this manual.
476 @node Plain lists, Footnotes, Sparse trees, Document Structure
479 Within an entry of the outline tree, hand-formatted lists can provide
480 additional structure. They also provide a way to create lists of
481 checkboxes (@pxref{Checkboxes}). Org supports editing such lists,
482 and the HTML exporter (@pxref{Exporting}) parses and formats them.
484 Org knows ordered lists, unordered lists, and description lists.
487 @emph{Unordered} list items start with @samp{-}, @samp{+}, or
490 @emph{Ordered} list items start with @samp{1.} or @samp{1)}.
492 @emph{Description} list use @samp{ :: } to separate the @emph{term} from the
496 Items belonging to the same list must have the same indentation on the first
497 line. An item ends before the next line that is indented like its
498 bullet/number, or less. A list ends when all items are closed, or before two
499 blank lines. An example:
504 My favorite scenes are (in this order)
505 1. The attack of the Rohirrim
506 2. Eowyn's fight with the witch king
507 + this was already my favorite scene in the book
508 + I really like Miranda Otto.
509 Important actors in this film are:
510 - @b{Elijah Wood} :: He plays Frodo
511 - @b{Sean Austin} :: He plays Sam, Frodo's friend.
515 The following commands act on items when the cursor is in the first line of
516 an item (the line with the bullet or number).
520 Items can be folded just like headline levels.
522 Insert new item at current level. With a prefix argument, force a new
523 heading (@pxref{Structure editing}).
525 Insert a new item with a checkbox (@pxref{Checkboxes}).
526 @item M-S-@key{up}@r{/}@key{down}
527 Move the item including subitems up/down (swap with previous/next item
528 of same indentation). If the list is ordered, renumbering is
530 @item M-@key{left}@r{/}M-@key{right}
531 Decrease/increase the indentation of an item, leaving children alone.
532 @item M-S-@key{left}@r{/}@key{right}
533 Decrease/increase the indentation of the item, including subitems.
535 If there is a checkbox (@pxref{Checkboxes}) in the item line, toggle the
536 state of the checkbox. Also verify bullets and indentation consistency in
539 Cycle the entire list level through the different itemize/enumerate bullets
540 (@samp{-}, @samp{+}, @samp{*}, @samp{1.}, @samp{1)}).
543 @node Footnotes, , Plain lists, Document Structure
546 A footnote is defined in a paragraph that is started by a footnote marker in
547 square brackets in column 0, no indentation allowed. The footnote reference
548 is simply the marker in square brackets, inside text. For example:
551 The Org homepage[fn:1] now looks a lot better than it used to.
553 [fn:1] The link is: http://orgmode.org
556 @noindent The following commands handle footnotes:
560 The footnote action command. When the cursor is on a footnote reference,
561 jump to the definition. When it is at a definition, jump to the (first)
562 reference. Otherwise, create a new footnote. When this command is called
563 with a prefix argument, a menu of additional options including renumbering is
567 Jump between definition and reference.
571 @uref{http://orgmode.org/manual/Document-Structure.html#Document-Structure,
572 Chapter 2 of the manual}@*
573 @uref{http://sachachua.com/wp/2008/01/outlining-your-notes-with-org/,
574 Sacha Chua's tutorial}}
577 @node Tables, Hyperlinks, Document Structure, Top
580 Org comes with a fast and intuitive table editor. Spreadsheet-like
581 calculations are supported in connection with the Emacs @file{calc}
584 (@pxref{Top,Calc,,Calc,Gnu Emacs Calculator Manual}).
587 (see the Emacs Calculator manual for more information about the Emacs
591 Org makes it easy to format tables in plain ASCII. Any line with
592 @samp{|} as the first non-whitespace character is considered part of a
593 table. @samp{|} is also the column separator. A table might look like
597 | Name | Phone | Age |
598 |-------+-------+-----|
599 | Peter | 1234 | 17 |
603 A table is re-aligned automatically each time you press @key{TAB} or
604 @key{RET} or @kbd{C-c C-c} inside the table. @key{TAB} also moves to
605 the next field (@key{RET} to the next row) and creates new table rows
606 at the end of the table or before horizontal lines. The indentation
607 of the table is set by the first line. Any line starting with
608 @samp{|-} is considered as a horizontal separator line and will be
609 expanded on the next re-align to span the whole table width. So, to
610 create the above table, you would only type
617 @noindent and then press @key{TAB} to align the table and start filling in
618 fields. Even faster would be to type @code{|Name|Phone|Age} followed by
621 When typing text into a field, Org treats @key{DEL},
622 @key{Backspace}, and all character keys in a special way, so that
623 inserting and deleting avoids shifting other fields. Also, when
624 typing @emph{immediately after the cursor was moved into a new field
625 with @kbd{@key{TAB}}, @kbd{S-@key{TAB}} or @kbd{@key{RET}}}, the
626 field is automatically made blank.
629 @tsubheading{Creation and conversion}
631 Convert the active region to table. If every line contains at least one TAB
632 character, the function assumes that the material is tab separated. If every
633 line contains a comma, comma-separated values (CSV) are assumed. If not,
634 lines are split at whitespace into fields.
636 If there is no active region, this command creates an empty Org
637 table. But it's easier just to start typing, like
638 @kbd{|Name|Phone|Age C-c @key{RET}}.
640 @tsubheading{Re-aligning and field motion}
642 Re-align the table without moving the cursor.
645 Re-align the table, move to the next field. Creates a new row if
649 Re-align, move to previous field.
652 Re-align the table and move down to next row. Creates a new row if
655 @tsubheading{Column and row editing}
658 Move the current column left/right.
661 Kill the current column.
663 @item M-S-@key{right}
664 Insert a new column to the left of the cursor position.
668 Move the current row up/down.
671 Kill the current row or horizontal line.
674 Insert a new row above the current row. With a prefix argument, the line is
675 created below the current one.
678 Insert a horizontal line below current row. With a prefix argument, the line
679 is created above the current line.
682 Insert a horizontal line below current row, and move the cursor into the row
686 Sort the table lines in the region. The position of point indicates the
687 column to be used for sorting, and the range of lines is the range
688 between the nearest horizontal separator lines, or the entire table.
693 @uref{http://orgmode.org/manual/Tables.html#Tables, Chapter 3 of the
695 @uref{http://orgmode.org/worg/org-tutorials/tables.php, Bastien's
697 @uref{http://orgmode.org/worg/org-tutorials/org-spreadsheet-intro.php,
698 Bastien's spreadsheet tutorial}@*
699 @uref{http://orgmode.org/worg/org-tutorials/org-plot.php, Eric's plotting tutorial}}
701 @node Hyperlinks, TODO Items, Tables, Top
704 Like HTML, Org provides links inside a file, external links to
705 other files, Usenet articles, emails, and much more.
708 * Link format:: How links in Org are formatted
709 * Internal links:: Links to other places in the current file
710 * External links:: URL-like links to the world
711 * Handling links:: Creating, inserting and following
712 * Targeted links:: Point at a location in a file
715 @node Link format, Internal links, Hyperlinks, Hyperlinks
718 Org will recognize plain URL-like links and activate them as
719 clickable links. The general link format, however, looks like this:
722 [[link][description]] @r{or alternatively} [[link]]
726 Once a link in the buffer is complete (all brackets present), Org will change
727 the display so that @samp{description} is displayed instead of
728 @samp{[[link][description]]} and @samp{link} is displayed instead of
729 @samp{[[link]]}. To edit the invisible @samp{link} part, use @kbd{C-c
730 C-l} with the cursor on the link.
732 @node Internal links, External links, Link format, Hyperlinks
733 @section Internal links
735 If the link does not look like a URL, it is considered to be internal in the
736 current file. The most important case is a link like
737 @samp{[[#my-custom-id]]} which will link to the entry with the
738 @code{CUSTOM_ID} property @samp{my-custom-id}.
740 Links such as @samp{[[My Target]]} or @samp{[[My Target][Find my target]]}
741 lead to a text search in the current file for the corresponding target which
742 looks like @samp{<<My Target>>}.
744 @node External links, Handling links, Internal links, Hyperlinks
745 @section External links
747 Org supports links to files, websites, Usenet and email messages,
748 BBDB database entries and links to both IRC conversations and their
749 logs. External links are URL-like locators. They start with a short
750 identifying string followed by a colon. There can be no space after
751 the colon. Here are some examples:
754 http://www.astro.uva.nl/~dominik @r{on the web}
755 file:/home/dominik/images/jupiter.jpg @r{file, absolute path}
756 /home/dominik/images/jupiter.jpg @r{same as above}
757 file:papers/last.pdf @r{file, relative path}
758 file:projects.org @r{another Org file}
759 docview:papers/last.pdf::NNN @r{open file in doc-view mode at page NNN}
760 id:B7423F4D-2E8A-471B-8810-C40F074717E9 @r{Link to heading by ID}
761 news:comp.emacs @r{Usenet link}
762 mailto:adent@@galaxy.net @r{Mail link}
763 vm:folder @r{VM folder link}
764 vm:folder#id @r{VM message link}
765 wl:folder#id @r{WANDERLUST message link}
766 mhe:folder#id @r{MH-E message link}
767 rmail:folder#id @r{RMAIL message link}
768 gnus:group#id @r{Gnus article link}
769 bbdb:R.*Stallman @r{BBDB link (with regexp)}
770 irc:/irc.com/#emacs/bob @r{IRC link}
771 info:org:External%20links @r{Info node link (with encoded space)}
774 A link should be enclosed in double brackets and may contain a
775 descriptive text to be displayed instead of the URL (@pxref{Link
776 format}), for example:
779 [[http://www.gnu.org/software/emacs/][GNU Emacs]]
783 If the description is a file name or URL that points to an image, HTML export
784 (@pxref{HTML export}) will inline the image as a clickable button. If there
785 is no description at all and the link points to an image, that image will be
786 inlined into the exported HTML file.
788 @node Handling links, Targeted links, External links, Hyperlinks
789 @section Handling links
791 Org provides methods to create a link in the correct syntax, to
792 insert it into an Org file, and to follow the link.
796 Store a link to the current location. This is a @emph{global} command (you
797 must create the key binding yourself) which can be used in any buffer to
798 create a link. The link will be stored for later insertion into an Org
802 Insert a link. This prompts for a link to be inserted into the buffer. You
803 can just type a link, or use history keys @key{up} and @key{down} to access
804 stored links. You will be prompted for the description part of the link.
805 When called with a @kbd{C-u} prefix argument, file name completion is used to
808 @item C-c C-l @r{(with cursor on existing link)}
809 When the cursor is on an existing link, @kbd{C-c C-l} allows you to edit the
810 link and description parts of the link.
812 @item C-c C-o @r{or} mouse-1 @r{or} mouse-2
815 Jump back to a recorded position. A position is recorded by the
816 commands following internal links, and by @kbd{C-c %}. Using this
817 command several times in direct succession moves through a ring of
818 previously recorded positions.
822 @node Targeted links, , Handling links, Hyperlinks
823 @section Targeted links
825 File links can contain additional information to make Emacs jump to a
826 particular location in the file when following a link. This can be a
827 line number or a search option after a double colon.
829 Here is the syntax of the different ways to attach a search to a file
830 link, together with an explanation:
833 [[file:~/code/main.c::255]] @r{Find line 255}
834 [[file:~/xx.org::My Target]] @r{Find @samp{<<My Target>>}}
835 [[file:~/xx.org::#my-custom-id]] @r{Find entry with custom id}
839 @uref{http://orgmode.org/manual/Hyperlinks.html#Hyperlinks, Chapter 4 of the
842 @node TODO Items, Tags, Hyperlinks, Top
845 Org mode does not maintain TODO lists as separate documents@footnote{Of
846 course, you can make a document that contains only long lists of TODO items,
847 but this is not required.}. Instead, TODO items are an integral part of the
848 notes file, because TODO items usually come up while taking notes! With Org
849 mode, simply mark any entry in a tree as being a TODO item. In this way,
850 information is not duplicated, and the entire context from which the TODO
851 item emerged is always present.
853 Of course, this technique for managing TODO items scatters them
854 throughout your notes file. Org mode compensates for this by providing
855 methods to give you an overview of all the things that you have to do.
858 * Using TODO states:: Setting and switching states
859 * Multi-state workflows:: More than just on/off
860 * Progress logging:: Dates and notes for progress
861 * Priorities:: Some things are more important than others
862 * Breaking down tasks:: Splitting a task into manageable pieces
863 * Checkboxes:: Tick-off lists
866 @node Using TODO states, Multi-state workflows, TODO Items, TODO Items
867 @section Using TODO states
869 Any headline becomes a TODO item when it starts with the word
870 @samp{TODO}, for example:
873 *** TODO Write letter to Sam Fortune
877 The most important commands to work with TODO entries are:
881 Rotate the TODO state of the current item among
884 ,-> (unmarked) -> TODO -> DONE --.
885 '--------------------------------'
888 The same rotation can also be done ``remotely'' from the timeline and
889 agenda buffers with the @kbd{t} command key (@pxref{Agenda commands}).
891 @item S-@key{right}@r{/}@key{left}
892 Select the following/preceding TODO state, similar to cycling.
894 View TODO items in a @emph{sparse tree} (@pxref{Sparse trees}). Folds the
895 buffer, but shows all TODO items and the headings hierarchy above
898 Show the global TODO list. Collects the TODO items from all agenda files
899 (@pxref{Agenda Views}) into a single buffer. @xref{Global TODO list}, for
902 Insert a new TODO entry below the current one.
906 Changing a TODO state can also trigger tag changes. See the docstring of the
907 option @code{org-todo-state-tags-triggers} for details.
909 @node Multi-state workflows, Progress logging, Using TODO states, TODO Items
910 @section Multi-state workflows
912 You can use TODO keywords to indicate different @emph{sequential} states
913 in the process of working on an item, for example:
916 (setq org-todo-keywords
917 '((sequence "TODO" "FEEDBACK" "VERIFY" "|" "DONE" "DELEGATED")))
920 The vertical bar separates the TODO keywords (states that @emph{need
921 action}) from the DONE states (which need @emph{no further action}). If
922 you don't provide the separator bar, the last state is used as the DONE
924 With this setup, the command @kbd{C-c C-t} will cycle an entry from TODO
925 to FEEDBACK, then to VERIFY, and finally to DONE and DELEGATED.
927 Sometimes you may want to use different sets of TODO keywords in
928 parallel. For example, you may want to have the basic
929 @code{TODO}/@code{DONE}, but also a workflow for bug fixing, and a
930 separate state indicating that an item has been canceled (so it is not
931 DONE, but also does not require action). Your setup would then look
935 (setq org-todo-keywords
936 '((sequence "TODO(t)" "|" "DONE(d)")
937 (sequence "REPORT(r)" "BUG(b)" "KNOWNCAUSE(k)" "|" "FIXED(f)")
938 (sequence "|" "CANCELED(c)")))
941 The keywords should all be different, this helps Org mode to keep track of
942 which subsequence should be used for a given entry. The example also shows
943 how to define keys for fast access of a particular state, by adding a letter
944 in parenthesis after each keyword - you will be prompted for the key after
947 To define TODO keywords that are valid only in a single file, use the
948 following text anywhere in the file.
951 #+TODO: TODO(t) | DONE(d)
952 #+TODO: REPORT(r) BUG(b) KNOWNCAUSE(k) | FIXED(f)
953 #+TODO: | CANCELED(c)
956 After changing one of these lines, use @kbd{C-c C-c} with the cursor still in
957 the line to make the changes known to Org mode.
959 @node Progress logging, Priorities, Multi-state workflows, TODO Items
960 @section Progress logging
962 Org mode can automatically record a timestamp and possibly a note when
963 you mark a TODO item as DONE, or even each time you change the state of
964 a TODO item. This system is highly configurable, settings can be on a
965 per-keyword basis and can be localized to a file or even a subtree. For
966 information on how to clock working time for a task, see @ref{Clocking
970 * Closing items:: When was this entry marked DONE?
971 * Tracking TODO state changes:: When did the status change?
974 @node Closing items, Tracking TODO state changes, Progress logging, Progress logging
975 @unnumberedsubsec Closing items
977 The most basic logging is to keep track of @emph{when} a certain TODO
978 item was finished. This is achieved with@footnote{The corresponding
979 in-buffer setting is: @code{#+STARTUP: logdone}}.
982 (setq org-log-done 'time)
986 Then each time you turn an entry from a TODO (not-done) state into any of the
987 DONE states, a line @samp{CLOSED: [timestamp]} will be inserted just after
988 the headline. If you want to record a note along with the timestamp,
989 use@footnote{The corresponding in-buffer setting is: @code{#+STARTUP:
993 (setq org-log-done 'note)
997 You will then be prompted for a note, and that note will be stored below
998 the entry with a @samp{Closing Note} heading.
1000 @node Tracking TODO state changes, , Closing items, Progress logging
1001 @unnumberedsubsec Tracking TODO state changes
1003 You might want to keep track of TODO state changes. You can either record
1004 just a timestamp, or a time-stamped note for a change. These records will be
1005 inserted after the headline as an itemized list. When taking a lot of notes,
1006 you might want to get the notes out of the way into a drawer. Customize the
1007 variable @code{org-log-into-drawer} to get this behavior.
1009 For state logging, Org mode expects configuration on a per-keyword basis.
1010 This is achieved by adding special markers @samp{!} (for a timestamp) and
1011 @samp{@@} (for a note) in parentheses after each keyword. For example:
1013 #+TODO: TODO(t) WAIT(w@@/!) | DONE(d!) CANCELED(c@@)
1016 will define TODO keywords and fast access keys, and also request that a time
1017 is recorded when the entry is set to DONE, and that a note is recorded when
1018 switching to WAIT or CANCELED. The same syntax works also when setting
1019 @code{org-todo-keywords}.
1021 @node Priorities, Breaking down tasks, Progress logging, TODO Items
1024 If you use Org mode extensively, you may end up with enough TODO items that
1025 it starts to make sense to prioritize them. Prioritizing can be done by
1026 placing a @emph{priority cookie} into the headline of a TODO item, like this
1029 *** TODO [#A] Write letter to Sam Fortune
1033 Org mode supports three priorities: @samp{A}, @samp{B}, and @samp{C}.
1034 @samp{A} is the highest, @samp{B} the default if none is given. Priorities
1035 make a difference only in the agenda.
1039 Set the priority of the current headline. Press @samp{A}, @samp{B} or
1040 @samp{C} to select a priority, or @key{SPC} to remove the cookie.
1044 Increase/decrease priority of current headline
1047 @node Breaking down tasks, Checkboxes, Priorities, TODO Items
1048 @section Breaking tasks down into subtasks
1050 It is often advisable to break down large tasks into smaller, manageable
1051 subtasks. You can do this by creating an outline tree below a TODO item,
1052 with detailed subtasks on the tree. To keep the overview over the fraction
1053 of subtasks that are already completed, insert either @samp{[/]} or
1054 @samp{[%]} anywhere in the headline. These cookies will be updated each time
1055 the TODO status of a child changes, or when pressing @kbd{C-c C-c} on the
1056 cookie. For example:
1059 * Organize Party [33%]
1060 ** TODO Call people [1/2]
1064 ** DONE Talk to neighbor
1067 @node Checkboxes, , Breaking down tasks, TODO Items
1070 Every item in a plain list (@pxref{Plain lists}) can be made into a checkbox
1071 by starting it with the string @samp{[ ]}. Checkboxes are not included into
1072 the global TODO list, so they are often great to split a task into a number
1074 Here is an example of a checkbox list.
1077 * TODO Organize party [1/3]
1078 - [-] call people [1/2]
1082 - [ ] think about what music to play
1085 Checkboxes work hierarchically, so if a checkbox item has children that
1086 are checkboxes, toggling one of the children checkboxes will make the
1087 parent checkbox reflect if none, some, or all of the children are
1090 @noindent The following commands work with checkboxes:
1094 Toggle checkbox status or (with prefix arg) checkbox presence at point.
1096 Insert a new item with a checkbox.
1097 This works only if the cursor is already in a plain list item
1098 (@pxref{Plain lists}).
1102 @uref{http://orgmode.org/manual/TODO-Items.html#TODO-Items, Chapter 5 of the manual}@*
1103 @uref{http://orgmode.org/worg/org-tutorials/orgtutorial_dto.php, David
1104 O'Toole's introductory tutorial}@*
1105 @uref{http://members.optusnet.com.au/~charles57/GTD/gtd_workflow.html,
1106 Charles Cave's GTD setup}}
1108 @node Tags, Properties, TODO Items, Top
1111 An excellent way to implement labels and contexts for cross-correlating
1112 information is to assign @i{tags} to headlines. Org mode has extensive
1115 Every headline can contain a list of tags; they occur at the end of the
1116 headline. Tags are normal words containing letters, numbers, @samp{_}, and
1117 @samp{@@}. Tags must be preceded and followed by a single colon, e.g.,
1118 @samp{:work:}. Several tags can be specified, as in @samp{:work:urgent:}.
1119 Tags will by default be in bold face with the same color as the headline.
1122 * Tag inheritance:: Tags use the tree structure of the outline
1123 * Setting tags:: How to assign tags to a headline
1124 * Tag searches:: Searching for combinations of tags
1127 @node Tag inheritance, Setting tags, Tags, Tags
1128 @section Tag inheritance
1130 @i{Tags} make use of the hierarchical structure of outline trees. If a
1131 heading has a certain tag, all subheadings will inherit the tag as
1132 well. For example, in the list
1135 * Meeting with the French group :work:
1136 ** Summary by Frank :boss:notes:
1137 *** TODO Prepare slides for him :action:
1141 the final heading will have the tags @samp{:work:}, @samp{:boss:},
1142 @samp{:notes:}, and @samp{:action:} even though the final heading is not
1143 explicitly marked with those tags. You can also set tags that all entries in
1144 a file should inherit just as if these tags were defined in a hypothetical
1145 level zero that surrounds the entire file. Use a line like this@footnote{As
1146 with all these in-buffer settings, pressing @kbd{C-c C-c} activates any
1147 changes in the line.}:
1150 #+FILETAGS: :Peter:Boss:Secret:
1153 @node Setting tags, Tag searches, Tag inheritance, Tags
1154 @section Setting tags
1156 Tags can simply be typed into the buffer at the end of a headline.
1157 After a colon, @kbd{M-@key{TAB}} offers completion on tags. There is
1158 also a special command for inserting tags:
1162 Enter new tags for the current headline. Org mode will either offer
1163 completion or a special single-key interface for setting tags, see
1164 below. After pressing @key{RET}, the tags will be inserted and aligned
1165 to @code{org-tags-column}. When called with a @kbd{C-u} prefix, all
1166 tags in the current buffer will be aligned to that column, just to make
1169 When the cursor is in a headline, this does the same as @kbd{C-c C-q}.
1172 Org will support tag insertion based on a @emph{list of tags}. By
1173 default this list is constructed dynamically, containing all tags
1174 currently used in the buffer. You may also globally specify a hard list
1175 of tags with the variable @code{org-tag-alist}. Finally you can set
1176 the default tags for a given file with lines like
1179 #+TAGS: @@work @@home @@tennisclub
1180 #+TAGS: laptop car pc sailboat
1183 By default Org mode uses the standard minibuffer completion facilities for
1184 entering tags. However, it also implements another, quicker, tag selection
1185 method called @emph{fast tag selection}. This allows you to select and
1186 deselect tags with just a single key press. For this to work well you should
1187 assign unique letters to most of your commonly used tags. You can do this
1188 globally by configuring the variable @code{org-tag-alist} in your
1189 @file{.emacs} file. For example, you may find the need to tag many items in
1190 different files with @samp{:@@home:}. In this case you can set something
1194 (setq org-tag-alist '(("@@work" . ?w) ("@@home" . ?h) ("laptop" . ?l)))
1197 @noindent If the tag is only relevant to the file you are working on, then you
1198 can instead set the TAGS option line as:
1201 #+TAGS: @@work(w) @@home(h) @@tennisclub(t) laptop(l) pc(p)
1204 @node Tag searches, , Setting tags, Tags
1205 @section Tag searches
1207 Once a system of tags has been set up, it can be used to collect related
1208 information into special lists.
1213 Create a sparse tree with all headlines matching a tags search. With a
1214 @kbd{C-u} prefix argument, ignore headlines that are not a TODO line.
1216 Create a global list of tag matches from all agenda files.
1217 @xref{Matching tags and properties}.
1219 Create a global list of tag matches from all agenda files, but check
1220 only TODO items and force checking subitems (see variable
1221 @code{org-tags-match-list-sublevels}).
1224 These commands all prompt for a match string which allows basic Boolean logic
1225 like @samp{+boss+urgent-project1}, to find entries with tags @samp{boss} and
1226 @samp{urgent}, but not @samp{project1}, or @samp{Kathy|Sally} to find entries
1227 which are tagged, like @samp{Kathy} or @samp{Sally}. The full syntax of the
1228 search string is rich and allows also matching against TODO keywords, entry
1229 levels and properties. For a complete description with many examples, see
1230 @ref{Matching tags and properties}.
1233 @uref{http://orgmode.org/manual/Tags.html#Tags, Chapter 6 of the manual}@*
1234 @uref{http://sachachua.com/wp/2008/01/tagging-in-org-plus-bonus-code-for-timeclocks-and-tags/,
1235 Sacha Chua's article about tagging in Org-mode}}
1237 @node Properties, Dates and Times, Tags, Top
1240 Properties are key-value pairs associates with and entry. They live in a
1241 special drawer with the name @code{PROPERTIES}. Each
1242 property is specified on a single line, with the key (surrounded by colons)
1243 first, and the value after it:
1248 *** Goldberg Variations
1250 :Title: Goldberg Variations
1251 :Composer: J.S. Bach
1252 :Publisher: Deutsche Grammophon
1257 You may define the allowed values for a particular property @samp{:Xyz:}
1258 by setting a property @samp{:Xyz_ALL:}. This special property is
1259 @emph{inherited}, so if you set it in a level 1 entry, it will apply to
1260 the entire tree. When allowed values are defined, setting the
1261 corresponding property becomes easier and is less prone to typing
1262 errors. For the example with the CD collection, we can predefine
1263 publishers and the number of disks in a box like this:
1268 :NDisks_ALL: 1 2 3 4
1269 :Publisher_ALL: "Deutsche Grammophon" Philips EMI
1272 or globally using @code{org-global-properties}, or file-wide like this:
1274 #+PROPERTY: NDisks_ALL 1 2 3 4
1279 Set a property. This prompts for a property name and a value.
1281 Remove a property from the current entry.
1284 To create sparse trees and special lists with selection based on properties,
1285 the same commands are used as for tag searches (@pxref{Tag searches}). The
1286 syntax for the search string is described in @ref{Matching tags and
1293 @uref{http://orgmode.org/manual/Properties-and-Columns.html#Properties-and-Columns,
1294 Chapter 7 of the manual}@*
1295 @uref{http://orgmode.org/worg/org-tutorials/org-column-view-tutorial.php,Bastien
1296 Guerry's column view tutorial}}
1298 @node Dates and Times, Capture - Refile - Archive, Properties, Top
1299 @chapter Dates and Times
1301 To assist project planning, TODO items can be labeled with a date and/or
1302 a time. The specially formatted string carrying the date and time
1303 information is called a @emph{timestamp} in Org mode.
1306 * Timestamps:: Assigning a time to a tree entry
1307 * Creating timestamps:: Commands which insert timestamps
1308 * Deadlines and scheduling:: Planning your work
1309 * Clocking work time:: Tracking how long you spend on a task
1313 @node Timestamps, Creating timestamps, Dates and Times, Dates and Times
1316 A timestamp is a specification of a date (possibly with a time or a range of
1317 times) in a special format, either @samp{<2003-09-16 Tue>} or
1318 @samp{<2003-09-16 Tue 09:39>} or @samp{<2003-09-16 Tue 12:00-12:30>}. A
1319 timestamp can appear anywhere in the headline or body of an Org tree entry.
1320 Its presence causes entries to be shown on specific dates in the agenda
1321 (@pxref{Weekly/daily agenda}). We distinguish:
1323 @noindent @b{Plain timestamp; Event; Appointment}@*
1324 A simple timestamp just assigns a date/time to an item. This is just
1325 like writing down an appointment or event in a paper agenda.
1328 * Meet Peter at the movies
1329 <2006-11-01 Wed 19:15>
1330 * Discussion on climate change
1331 <2006-11-02 Thu 20:00-22:00>
1334 @noindent @b{Timestamp with repeater interval}@*
1335 A timestamp may contain a @emph{repeater interval}, indicating that it
1336 applies not only on the given date, but again and again after a certain
1337 interval of N days (d), weeks (w), months (m), or years (y). The
1338 following will show up in the agenda every Wednesday:
1340 * Pick up Sam at school
1341 <2007-05-16 Wed 12:30 +1w>
1344 @noindent @b{Diary-style sexp entries}@*
1345 For more complex date specifications, Org mode supports using the
1346 special sexp diary entries implemented in the Emacs calendar/diary
1347 package. For example
1349 * The nerd meeting on every 2nd Thursday of the month
1350 <%%(diary-float t 4 2)>
1353 @noindent @b{Time/Date range}@*
1354 Two timestamps connected by @samp{--} denote a range.
1356 ** Meeting in Amsterdam
1357 <2004-08-23 Mon>--<2004-08-26 Thu>
1360 @noindent @b{Inactive timestamp}@*
1361 Just like a plain timestamp, but with square brackets instead of
1362 angular ones. These timestamps are inactive in the sense that they do
1363 @emph{not} trigger an entry to show up in the agenda.
1366 * Gillian comes late for the fifth time
1371 @node Creating timestamps, Deadlines and scheduling, Timestamps, Dates and Times
1372 @section Creating timestamps
1374 For Org mode to recognize timestamps, they need to be in the specific
1375 format. All commands listed below produce timestamps in the correct
1380 Prompt for a date and insert a corresponding timestamp. When the cursor is
1381 at an existing timestamp in the buffer, the command is used to modify this
1382 timestamp instead of inserting a new one. When this command is used twice in
1383 succession, a time range is inserted. With a prefix, also add the current
1387 Like @kbd{C-c .}, but insert an inactive timestamp that will not cause
1390 @item S-@key{left}@r{/}@key{right}
1391 Change date at cursor by one day.
1393 @item S-@key{up}@r{/}@key{down}
1394 Change the item under the cursor in a timestamp. The cursor can be on a
1395 year, month, day, hour or minute. When the timestamp contains a time range
1396 like @samp{15:30-16:30}, modifying the first time will also shift the second,
1397 shifting the time block with constant length. To change the length, modify
1401 When Org mode prompts for a date/time, it will accept any string containing
1402 some date and/or time information, and intelligently interpret the string,
1403 deriving defaults for unspecified information from the current date and time.
1404 You can also select a date in the pop-up calendar. See the manual for more
1405 information on how exactly the date/time prompt works.
1407 @node Deadlines and scheduling, Clocking work time, Creating timestamps, Dates and Times
1408 @section Deadlines and scheduling
1410 A timestamp may be preceded by special keywords to facilitate planning:
1412 @noindent @b{DEADLINE}@*
1413 Meaning: the task (most likely a TODO item, though not necessarily) is supposed
1414 to be finished on that date.
1417 Insert @samp{DEADLINE} keyword along with a stamp, in the line following the
1421 On the deadline date, the task will be listed in the agenda. In
1422 addition, the agenda for @emph{today} will carry a warning about the
1423 approaching or missed deadline, starting
1424 @code{org-deadline-warning-days} before the due date, and continuing
1425 until the entry is marked DONE. An example:
1428 *** TODO write article about the Earth for the Guide
1429 The editor in charge is [[bbdb:Ford Prefect]]
1430 DEADLINE: <2004-02-29 Sun>
1434 @noindent @b{SCHEDULED}@*
1435 Meaning: you are @i{planning to start working} on that task on the given
1436 date@footnote{This is quite different from what is normally understood by
1437 @i{scheduling a meeting}, which is done in Org-mode by just inserting a time
1438 stamp without keyword.}.
1442 Insert @samp{SCHEDULED} keyword along with a stamp, in the line following the
1446 The headline will be listed under the given date@footnote{It will still
1447 be listed on that date after it has been marked DONE. If you don't like
1448 this, set the variable @code{org-agenda-skip-scheduled-if-done}.}. In
1449 addition, a reminder that the scheduled date has passed will be present
1450 in the compilation for @emph{today}, until the entry is marked DONE.
1451 I.e.@: the task will automatically be forwarded until completed.
1454 *** TODO Call Trillian for a date on New Years Eve.
1455 SCHEDULED: <2004-12-25 Sat>
1458 Some tasks need to be repeated again and again. Org mode helps to
1459 organize such tasks using a so-called repeater in a DEADLINE, SCHEDULED,
1460 or plain timestamp. In the following example
1462 ** TODO Pay the rent
1463 DEADLINE: <2005-10-01 Sat +1m>
1466 the @code{+1m} is a repeater; the intended interpretation is that the task
1467 has a deadline on <2005-10-01> and repeats itself every (one) month starting
1470 @node Clocking work time, , Deadlines and scheduling, Dates and Times
1471 @section Clocking work time
1473 Org mode allows you to clock the time you spend on specific tasks in a
1478 Start the clock on the current item (clock-in). This inserts the CLOCK
1479 keyword together with a timestamp. When called with a @kbd{C-u} prefix
1480 argument, select the task from a list of recently clocked tasks.
1483 Stop the clock (clock-out). This inserts another timestamp at the same
1484 location where the clock was last started. It also directly computes
1485 the resulting time in inserts it after the time range as @samp{=>
1488 Update the effort estimate for the current clock task.
1490 Cancel the current clock. This is useful if a clock was started by
1491 mistake, or if you ended up working on something else.
1493 Jump to the entry that contains the currently running clock. With a
1494 @kbd{C-u} prefix arg, select the target task from a list of recently clocked
1497 Insert a dynamic block containing a clock
1498 report as an Org-mode table into the current file. When the cursor is
1499 at an existing clock table, just update it.
1501 #+BEGIN: clocktable :maxlevel 2 :emphasize nil :scope file
1505 For details about how to customize this view, see @uref{http://orgmode.org/manual/Clocking-work-time.html#Clocking-work-time,the manual}.
1507 Update dynamic block at point. The cursor needs to be in the
1508 @code{#+BEGIN} line of the dynamic block.
1511 The @kbd{l} key may be used in the timeline (@pxref{Timeline}) and in
1512 the agenda (@pxref{Weekly/daily agenda}) to show which tasks have been
1513 worked on or closed during a day.
1516 @uref{http://orgmode.org/manual/Dates-and-Times.html#Dates-and-Times,
1517 Chapter 8 of the manual}@*
1518 @uref{http://members.optusnet.com.au/~charles57/GTD/org_dates/, Charles
1519 Cave's Date and Time tutorial}@*
1520 @uref{http://doc.norang.ca/org-mode.html#Clocking, Bernt Hansen's clocking workflow}}
1522 @node Capture - Refile - Archive, Agenda Views, Dates and Times, Top
1523 @chapter Capture - Refile - Archive
1525 An important part of any organization system is the ability to quickly
1526 capture new ideas and tasks, and to associate reference material with them.
1527 Org defines a capture process to create tasks. It stores files related to a
1528 task (@i{attachments}) in a special directory. Once in the system, tasks and
1529 projects need to be moved around. Moving completed project trees to an
1530 archive file keeps the system compact and fast.
1534 * Refiling notes:: Moving a tree from one place to another
1535 * Archiving:: What to do with finished projects
1538 @node Capture, Refiling notes, Capture - Refile - Archive, Capture - Refile - Archive
1541 Org's method for capturing new items is heavily inspired by John Wiegley
1542 excellent remember package. It lets you store quick notes with little
1543 interruption of your work flow. Org lets you define templates for new
1544 entries and associate them with different targets for storing notes.
1547 * Setting up a capture location:: Where notes will be stored
1548 * Using capture:: Commands to invoke and terminate capture
1549 * Capture templates:: Define the outline of different note types
1552 @node Setting up a capture location, Using capture, Capture, Capture
1553 @unnumberedsubsec Setting up a capture location
1555 The following customization sets a default target@footnote{Using capture
1556 templates, you can define more fine-grained capture locations, see
1557 @ref{Capture templates}.} file for notes, and defines a global
1558 key@footnote{Please select your own key, @kbd{C-c c} is only a suggestion.}
1559 for capturing new stuff.
1562 (setq org-default-notes-file (concat org-directory "/notes.org"))
1563 (define-key global-map "\C-cc" 'org-capture)
1566 @node Using capture, Capture templates, Setting up a capture location, Capture
1567 @unnumberedsubsec Using capture
1571 Start a capture process. You will be placed into a narrowed indirect buffer
1574 Once you are done entering information into the capture buffer,
1575 @kbd{C-c C-c} will return you to the window configuration before the capture
1576 process, so that you can resume your work without further distraction.
1578 Finalize by moving the entry to a refile location (@pxref{Refiling notes}).
1580 Abort the capture process and return to the previous state.
1583 @node Capture templates, , Using capture, Capture
1584 @unnumberedsubsec Capture templates
1586 You can use templates to generate different types of capture notes, and to
1587 store them in different places. For example, if you would like
1588 to store new tasks under a heading @samp{Tasks} in file @file{TODO.org}, and
1589 journal entries in a date tree in @file{journal.org} you could
1593 (setq org-capture-templates
1594 '(("t" "Todo" entry (file+headline "~/org/gtd.org" "Tasks")
1595 "* TODO %?\n %i\n %a")
1596 ("j" "Journal" entry (file+datetree "~/org/journal.org")
1597 "* %?\nEntered on %U\n %i\n %a")))
1600 @noindent In these entries, the first string is the key to reach the
1601 template, the second is a short description. Then follows the type of the
1602 entry and a definition of the target location for storing the note. Finally,
1603 the template itself, a string with %-escapes to fill in information based on
1606 When you call @kbd{M-x org-capture}, Org will prompt for a key to select the
1607 template (if you have more than one template) and then prepare the buffer like
1610 [[file:@var{link to where you were when initiating capture}]]
1614 During expansion of the template, special @kbd{%}-escapes@footnote{If you
1615 need one of these sequences literally, escape the @kbd{%} with a backslash.}
1616 allow dynamic insertion of content. Here is a small selection of the
1617 possibilities, consult the manual for more.
1619 %a @r{annotation, normally the link created with @code{org-store-link}}
1620 %i @r{initial content, the region when remember is called with C-u.}
1621 %t @r{timestamp, date only}
1622 %T @r{timestamp with date and time}
1623 %u, %U @r{like the above, but inactive timestamps}
1626 @node Refiling notes, Archiving, Capture, Capture - Refile - Archive
1627 @section Refiling notes
1629 When reviewing the captured data, you may want to refile some of the entries
1630 into a different list, for example into a project. Cutting, finding the
1631 right location, and then pasting the note is cumbersome. To simplify this
1632 process, you can use the following special command:
1636 Refile the entry or region at point. This command offers possible locations
1637 for refiling the entry and lets you select one with completion. The item (or
1638 all items in the region) is filed below the target heading as a subitem.@*
1639 By default, all level 1 headlines in the current buffer are considered to be
1640 targets, but you can have more complex definitions across a number of files.
1641 See the variable @code{org-refile-targets} for details.
1643 Use the refile interface to jump to a heading.
1644 @item C-u C-u C-c C-w
1645 Jump to the location where @code{org-refile} last moved a tree to.
1648 @node Archiving, , Refiling notes, Capture - Refile - Archive
1651 When a project represented by a (sub)tree is finished, you may want
1652 to move the tree out of the way and to stop it from contributing to the
1653 agenda. Archiving is important to keep your working files compact and global
1654 searches like the construction of agenda views fast.
1655 The most common archiving action is to move a project tree to another file,
1660 Archive the current entry using the command specified in the variable
1661 @code{org-archive-default-command}.
1662 @item C-c C-x C-s@ @r{or short} @ C-c $
1663 Archive the subtree starting at the cursor position to the location
1664 given by @code{org-archive-location}.
1667 The default archive location is a file in the same directory as the
1668 current file, with the name derived by appending @file{_archive} to the
1669 current file name. For information and examples on how to change this,
1670 see the documentation string of the variable
1671 @code{org-archive-location}. There is also an in-buffer option for
1672 setting this variable, for example
1675 #+ARCHIVE: %s_done::
1679 @uref{http://orgmode.org/manual/Capture-_002d-Refile-_002d-Archive.html#Capture-_002d-Refile-_002d-Archive,
1680 Chapter 9 of the manual}@*
1681 @uref{http://members.optusnet.com.au/~charles57/GTD/remember.html, Charles
1682 Cave's remember tutorial}@*
1683 @uref{http://orgmode.org/worg/org-tutorials/org-protocol-custom-handler.php,
1684 Sebastian Rose's tutorial for capturing from a web browser}}@uref{}@*
1686 @node Agenda Views, Markup, Capture - Refile - Archive, Top
1687 @chapter Agenda Views
1689 Due to the way Org works, TODO items, time-stamped items, and tagged
1690 headlines can be scattered throughout a file or even a number of files. To
1691 get an overview of open action items, or of events that are important for a
1692 particular date, this information must be collected, sorted and displayed in
1693 an organized way. There are several different views, see below.
1695 The extracted information is displayed in a special @emph{agenda buffer}.
1696 This buffer is read-only, but provides commands to visit the corresponding
1697 locations in the original Org files, and even to edit these files remotely.
1698 Remote editing from the agenda buffer means, for example, that you can
1699 change the dates of deadlines and appointments from the agenda buffer.
1700 The commands available in the Agenda buffer are listed in @ref{Agenda
1704 * Agenda files:: Files being searched for agenda information
1705 * Agenda dispatcher:: Keyboard access to agenda views
1706 * Built-in agenda views:: What is available out of the box?
1707 * Agenda commands:: Remote editing of Org trees
1708 * Custom agenda views:: Defining special searches and views
1711 @node Agenda files, Agenda dispatcher, Agenda Views, Agenda Views
1712 @section Agenda files
1714 The information to be shown is normally collected from all @emph{agenda
1715 files}, the files listed in the variable
1716 @code{org-agenda-files}.
1720 Add current file to the list of agenda files. The file is added to
1721 the front of the list. If it was already in the list, it is moved to
1722 the front. With a prefix argument, file is added/moved to the end.
1724 Remove current file from the list of agenda files.
1726 Cycle through agenda file list, visiting one file after the other.
1729 @node Agenda dispatcher, Built-in agenda views, Agenda files, Agenda Views
1730 @section The agenda dispatcher
1731 The views are created through a dispatcher, which should be bound to a
1732 global key---for example @kbd{C-c a} (@pxref{Installation}). After
1733 pressing @kbd{C-c a}, an additional letter is required to execute a
1737 The calendar-like agenda (@pxref{Weekly/daily agenda}).
1739 A list of all TODO items (@pxref{Global TODO list}).
1741 A list of headlines matching a TAGS expression (@pxref{Matching
1742 tags and properties}).
1744 The timeline view for the current buffer (@pxref{Timeline}).
1746 A list of entries selected by a boolean expression of keywords
1747 and/or regular expressions that must or must not occur in the entry.
1750 @node Built-in agenda views, Agenda commands, Agenda dispatcher, Agenda Views
1751 @section The built-in agenda views
1754 * Weekly/daily agenda:: The calendar page with current tasks
1755 * Global TODO list:: All unfinished action items
1756 * Matching tags and properties:: Structured information with fine-tuned search
1757 * Timeline:: Time-sorted view for single file
1758 * Search view:: Find entries by searching for text
1761 @node Weekly/daily agenda, Global TODO list, Built-in agenda views, Built-in agenda views
1762 @subsection The weekly/daily agenda
1764 The purpose of the weekly/daily @emph{agenda} is to act like a page of a
1765 paper agenda, showing all the tasks for the current week or day.
1769 Compile an agenda for the current week from a list of Org files. The agenda
1770 shows the entries for each day.
1773 Emacs contains the calendar and diary by Edward M. Reingold. Org-mode
1774 understands the syntax of the diary and allows you to use diary sexp entries
1775 directly in Org files:
1778 * Birthdays and similar stuff
1780 %%(org-calendar-holiday) ; special function for holiday names
1782 %%(diary-anniversary 5 14 1956)@footnote{Note that the order of the arguments (month, day, year) depends on the setting of @code{calendar-date-style}.} Arthur Dent is %d years old
1783 %%(diary-anniversary 10 2 1869) Mahatma Gandhi would be %d years old
1786 Org can interact with Emacs appointments notification facility. To add all
1787 the appointments of your agenda files, use the command
1788 @code{org-agenda-to-appt}. See the docstring for details.
1790 @node Global TODO list, Matching tags and properties, Weekly/daily agenda, Built-in agenda views
1791 @subsection The global TODO list
1793 The global TODO list contains all unfinished TODO items formatted and
1794 collected into a single place. Remote editing of TODO items lets you
1795 can change the state of a TODO entry with a single key press. The commands
1796 available in the TODO list are described in @ref{Agenda commands}.
1800 Show the global TODO list. This collects the TODO items from all
1801 agenda files (@pxref{Agenda Views}) into a single buffer.
1803 Like the above, but allows selection of a specific TODO keyword.
1806 @node Matching tags and properties, Timeline, Global TODO list, Built-in agenda views
1807 @subsection Matching tags and properties
1809 If headlines in the agenda files are marked with @emph{tags} (@pxref{Tags}),
1810 or have properties (@pxref{Properties}), you can select headlines
1811 based on this metadata and collect them into an agenda buffer. The match
1812 syntax described here also applies when creating sparse trees with @kbd{C-c /
1813 m}. The commands available in the tags list are described in @ref{Agenda
1818 Produce a list of all headlines that match a given set of tags. The
1819 command prompts for a selection criterion, which is a boolean logic
1820 expression with tags, like @samp{+work+urgent-withboss} or
1821 @samp{work|home} (@pxref{Tags}). If you often need a specific search,
1822 define a custom command for it (@pxref{Agenda dispatcher}).
1824 Like @kbd{C-c a m}, but only select headlines that are also TODO items.
1827 @subsubheading Match syntax
1829 A search string can use Boolean operators @samp{&} for AND and @samp{|} for
1830 OR. @samp{&} binds more strongly than @samp{|}. Parentheses are currently
1831 not implemented. Each element in the search is either a tag, a regular
1832 expression matching tags, or an expression like @code{PROPERTY OPERATOR
1833 VALUE} with a comparison operator, accessing a property value. Each element
1834 may be preceded by @samp{-}, to select against it, and @samp{+} is syntactic
1835 sugar for positive selection. The AND operator @samp{&} is optional when
1836 @samp{+} or @samp{-} is present. Here are some examples, using only tags.
1840 Select headlines tagged @samp{:work:}, but discard those also tagged
1843 Selects lines tagged @samp{:work:} or @samp{:laptop:}.
1844 @item work|laptop+night
1845 Like before, but require the @samp{:laptop:} lines to be tagged also
1849 You may also test for properties at the same
1850 time as matching tags, see the manual for more information.
1852 @node Timeline, Search view, Matching tags and properties, Built-in agenda views
1853 @subsection Timeline for a single file
1855 The timeline summarizes all time-stamped items from a single Org mode
1856 file in a @emph{time-sorted view}. The main purpose of this command is
1857 to give an overview over events in a project.
1861 Show a time-sorted view of the Org file, with all time-stamped items.
1862 When called with a @kbd{C-u} prefix, all unfinished TODO entries
1863 (scheduled or not) are also listed under the current date.
1866 @node Search view, , Timeline, Built-in agenda views
1867 @subsection Search view
1869 This agenda view is a general text search facility for Org mode entries.
1870 It is particularly useful to find notes.
1874 This is a special search that lets you select entries by matching a substring
1875 or specific words using a boolean logic.
1877 For example, the search string @samp{computer equipment} will find entries
1878 that contain @samp{computer equipment} as a substring.
1879 Search view can also search for specific keywords in the entry, using Boolean
1880 logic. The search string @samp{+computer +wifi -ethernet -@{8\.11[bg]@}}
1881 will search for note entries that contain the keywords @code{computer}
1882 and @code{wifi}, but not the keyword @code{ethernet}, and which are also
1883 not matched by the regular expression @code{8\.11[bg]}, meaning to
1884 exclude both 8.11b and 8.11g.
1886 Note that in addition to the agenda files, this command will also search
1887 the files listed in @code{org-agenda-text-search-extra-files}.
1889 @node Agenda commands, Custom agenda views, Built-in agenda views, Agenda Views
1890 @section Commands in the agenda buffer
1892 Entries in the agenda buffer are linked back to the Org file or diary
1893 file where they originate. Commands are provided to show and jump to the
1894 original entry location, and to edit the Org files ``remotely'' from
1895 the agenda buffer. This is just a selection of the many commands, explore
1896 the @code{Agenda} menu and the manual for a complete list.
1899 @tsubheading{Motion}
1901 Next line (same as @key{up} and @kbd{C-p}).
1903 Previous line (same as @key{down} and @kbd{C-n}).
1904 @tsubheading{View/Go to Org file}
1907 Display the original location of the item in another window.
1908 With prefix arg, make sure that the entire entry is made visible in the
1909 outline, not only the heading.
1912 Go to the original location of the item in another window. Under Emacs
1913 22, @kbd{mouse-1} will also work for this.
1916 Go to the original location of the item and delete other windows.
1919 @tsubheading{Change display}
1921 Delete other windows.
1924 Switch to day/week view.
1927 Go forward/backward in time to display the following
1928 @code{org-agenda-current-span} days. For example, if the display covers a
1929 week, switch to the following/previous week.
1935 Prompt for a date and go there.
1937 @item v l @ @r{or short} @ l
1938 Toggle Logbook mode. In Logbook mode, entries that were marked DONE while
1939 logging was on (variable @code{org-log-done}) are shown in the agenda, as are
1940 entries that have been clocked on that day. When called with a @kbd{C-u}
1941 prefix, show all possible logbook entries, including state changes.
1944 Recreate the agenda buffer, to reflect the changes.
1946 Save all Org buffers in the current Emacs session, and also the locations of
1949 @tsubheading{Secondary filtering and query editing}
1952 Filter the current agenda view with respect to a tag. You are prompted for a
1953 letter to select a tag. Press @samp{-} first to select against the tag.
1956 Narrow the current agenda filter by an additional condition.
1958 @tsubheading{Remote editing (see the manual for many more commands)}
1964 Change the TODO state of the item, in the agenda and in the
1968 Delete the current agenda item along with the entire subtree belonging
1969 to it in the original Org file.
1972 Refile the entry at point.
1974 @item C-c C-x C-a @ @r{or short} @ a
1975 Archive the subtree corresponding to the entry at point using the default
1976 archiving command set in @code{org-archive-default-command}.
1978 @item C-c C-x C-s @ @r{or short} @ $
1979 Archive the subtree corresponding to the current headline.
1982 Schedule this item, with prefix arg remove the scheduling timestamp
1985 Set a deadline for this item, with prefix arg remove the deadline.
1987 @item S-@key{right} @r{and} S-@key{left}
1988 Change the timestamp associated with the current line by one day.
1991 Start the clock on the current item.
1994 Stop/cancel the previously started clock.
1997 Jump to the running clock in another window.
2000 @node Custom agenda views, , Agenda commands, Agenda Views
2001 @section Custom agenda views
2003 The main application of custom searches is the definition of keyboard
2004 shortcuts for frequently used searches, either creating an agenda
2005 buffer, or a sparse tree (the latter covering of course only the current
2007 Custom commands are configured in the variable
2008 @code{org-agenda-custom-commands}. You can customize this variable, for
2009 example by pressing @kbd{C-c a C}. You can also directly set it with
2010 Emacs Lisp in @file{.emacs}. The following example contains all valid
2015 (setq org-agenda-custom-commands
2016 '(("w" todo "WAITING")
2017 ("u" tags "+boss-urgent")
2018 ("v" tags-todo "+boss-urgent")))
2023 The initial string in each entry defines the keys you have to press after the
2024 dispatcher command @kbd{C-c a} in order to access the command. Usually this
2025 will be just a single character. The second parameter is the search type,
2026 followed by the string or regular expression to be used for the matching.
2027 The example above will therefore define:
2031 as a global search for TODO entries with @samp{WAITING} as the TODO
2034 as a global tags search for headlines marked @samp{:boss:} but not
2037 as the same search as @kbd{C-c a u}, but limiting the search to
2038 headlines that are also TODO items
2042 @uref{http://orgmode.org/manual/Agenda-Views.html#Agenda-Views, Chapter 10 of
2044 @uref{http://orgmode.org/worg/org-tutorials/org-custom-agenda-commands.php,
2045 Mat Lundin's tutorial about custom agenda commands}@*
2046 @uref{http://www.newartisans.com/2007/08/using-org-mode-as-a-day-planner.html,
2047 John Wiegley's setup}}
2049 @node Markup, Exporting, Agenda Views, Top
2050 @chapter Markup for rich export
2052 When exporting Org-mode documents, the exporter tries to reflect the
2053 structure of the document as accurately as possible in the backend. Since
2054 export targets like HTML, @LaTeX{}, or DocBook allow much richer formatting,
2055 Org mode has rules on how to prepare text for rich export. This section
2056 summarizes the markup rules used in an Org-mode buffer.
2059 * Structural markup elements:: The basic structure as seen by the exporter
2060 * Images and tables:: Tables and Images will be included
2061 * Literal examples:: Source code examples with special formatting
2062 * Include files:: Include additional files into a document
2063 * Embedded @LaTeX{}:: @LaTeX{} can be freely used inside Org documents
2066 @node Structural markup elements, Images and tables, Markup, Markup
2067 @section Structural markup elements
2070 * Document title:: Where the title is taken from
2071 * Headings and sections:: The document structure as seen by the exporter
2072 * Table of contents:: The if and where of the table of contents
2073 * Paragraphs:: Paragraphs
2074 * Emphasis and monospace:: Bold, italic, etc.
2075 * Comment lines:: What will *not* be exported
2078 @node Document title, Headings and sections, Structural markup elements, Structural markup elements
2079 @subheading Document title
2082 The title of the exported document is taken from the special line
2085 #+TITLE: This is the title of the document
2088 @node Headings and sections, Table of contents, Document title, Structural markup elements
2089 @subheading Headings and sections
2091 The outline structure of the document as described in @ref{Document
2092 Structure}, forms the basis for defining sections of the exported document.
2093 However, since the outline structure is also used for (for example) lists of
2094 tasks, only the first three outline levels will be used as headings. Deeper
2095 levels will become itemized lists. You can change the location of this
2096 switch globally by setting the variable @code{org-export-headline-levels}, or on a
2097 per-file basis with a line
2103 @node Table of contents, Paragraphs, Headings and sections, Structural markup elements
2104 @subheading Table of contents
2106 The table of contents is normally inserted directly before the first headline
2110 #+OPTIONS: toc:2 (only to two levels in TOC)
2111 #+OPTIONS: toc:nil (no TOC at all)
2114 @node Paragraphs, Emphasis and monospace, Table of contents, Structural markup elements
2115 @subheading Paragraphs, line breaks, and quoting
2117 Paragraphs are separated by at least one empty line. If you need to enforce
2118 a line break within a paragraph, use @samp{\\} at the end of a line.
2120 To keep the line breaks in a region, but otherwise use normal formatting, you
2121 can use this construct, which can also be used to format poetry.
2125 Great clouds overhead
2126 Tiny black birds rise and fall
2133 When quoting a passage from another document, it is customary to format this
2134 as a paragraph that is indented on both the left and the right margin. You
2135 can include quotations in Org-mode documents like this:
2139 Everything should be made as simple as possible,
2140 but not any simpler -- Albert Einstein
2144 If you would like to center some text, do it like this:
2147 Everything should be made as simple as possible, \\
2152 @node Emphasis and monospace, Comment lines, Paragraphs, Structural markup elements
2153 @subheading Emphasis and monospace
2155 You can make words @b{*bold*}, @i{/italic/}, _underlined_, @code{=code=}
2156 and @code{~verbatim~}, and, if you must, @samp{+strike-through+}. Text
2157 in the code and verbatim string is not processed for Org-mode specific
2158 syntax, it is exported verbatim. To insert a horizontal rules, use a line
2159 consisting of only dashes, and at least 5 of them.
2161 @node Comment lines, , Emphasis and monospace, Structural markup elements
2162 @subheading Comment lines
2164 Lines starting with @samp{#} in column zero are treated as comments and will
2165 never be exported. If you want an indented line to be treated as a comment,
2166 start it with @samp{#+ }. Also entire subtrees starting with the word
2167 @samp{COMMENT} will never be exported. Finally, regions surrounded by
2168 @samp{#+BEGIN_COMMENT} ... @samp{#+END_COMMENT} will not be exported.
2172 Toggle the COMMENT keyword at the beginning of an entry.
2175 @node Images and tables, Literal examples, Structural markup elements, Markup
2176 @section Images and Tables
2178 For Org mode tables, the lines before the first horizontal separator line
2179 will become table header lines. You can use the following lines somewhere
2180 before the table to assign a caption and a label for cross references, and in
2181 the text you can refer to the object with @code{\ref@{tab:basic-data@}}:
2184 #+CAPTION: This is the caption for the next table (or link)
2185 #+LABEL: tbl:basic-data
2190 Some backends (HTML, @LaTeX{}, and DocBook) allow you to directly include
2191 images into the exported document. Org does this, if a link to an image
2192 files does not have a description part, for example @code{[[./img/a.jpg]]}.
2193 If you wish to define a caption for the image and maybe a label for internal
2194 cross references, you sure that the link is on a line by itself precede it
2198 #+CAPTION: This is the caption for the next figure link (or table)
2199 #+LABEL: fig:SED-HR4049
2203 You may also define additional attributes for the figure. As this is
2204 backend-specific, see the sections about the individual backends for more
2208 @node Literal examples, Include files, Images and tables, Markup
2209 @section Literal examples
2211 You can include literal examples that should not be subjected to
2212 markup. Such examples will be typeset in monospace, so this is well suited
2213 for source code and similar examples.
2217 Some example from a text file.
2221 For simplicity when using small examples, you can also start the example
2222 lines with a colon followed by a space. There may also be additional
2223 whitespace before the colon:
2227 : Some example from a text file.
2230 For source code from a programming language, or any other text
2231 that can be marked up by font-lock in Emacs, you can ask for it to
2232 look like the fontified Emacs buffer
2235 #+BEGIN_SRC emacs-lisp
2236 (defun org-xor (a b)
2242 To edit the example in a special buffer supporting this language, use
2243 @kbd{C-c '} to both enter and leave the editing buffer.
2245 @node Include files, Embedded @LaTeX{}, Literal examples, Markup
2246 @section Include files
2248 During export, you can include the content of another file. For example, to
2249 include your @file{.emacs} file, you could use:
2252 #+INCLUDE: "~/.emacs" src emacs-lisp
2255 The optional second and third parameter are the markup (e.g.@: @samp{quote},
2256 @samp{example}, or @samp{src}), and, if the markup is @samp{src}, the
2257 language for formatting the contents. The markup is optional, if it is not
2258 given, the text will be assumed to be in Org mode format and will be
2259 processed normally. @kbd{C-c '} will visit the included file.
2261 @node Embedded @LaTeX{}, , Include files, Markup
2262 @section Embedded @LaTeX{}
2264 For scientific notes which need to be able to contain mathematical symbols
2265 and the occasional formula, Org-mode supports embedding @LaTeX{} code into
2266 its files. You can directly use TeX-like macros for special symbols, enter
2267 formulas and entire @LaTeX{} environments.
2270 Angles are written as Greek letters \alpha, \beta and \gamma. The mass if
2271 the sun is M_sun = 1.989 x 10^30 kg. The radius of the sun is R_@{sun@} =
2272 6.96 x 10^8 m. If $a^2=b$ and $b=2$, then the solution must be either
2273 $a=+\sqrt@{2@}$ or $a=-\sqrt@{2@}$.
2280 @uref{http://orgmode.org/manual/LaTeX-fragments.html#LaTeX-fragments,special
2281 setup}, @LaTeX{} snippets will be included as images when exporting to HTML.
2284 @uref{http://orgmode.org/manual/Markup.html#Markup, Chapter 11 of the manual}}
2286 @node Exporting, Publishing, Markup, Top
2289 Org-mode documents can be exported into a variety of other formats: ASCII
2290 export for inclusion into emails, HTML to publish on the web, @LaTeX{}/PDF
2291 for beautiful printed documents and DocBook to enter the world of many other
2292 formats using DocBook tools. There is also export to iCalendar format so
2293 that planning information can be incorporated into desktop calendars.
2296 * Export options:: Per-file export settings
2297 * The export dispatcher:: How to access exporter commands
2298 * ASCII/Latin-1/UTF-8 export:: Exporting to flat files with encoding
2299 * HTML export:: Exporting to HTML
2300 * @LaTeX{} and PDF export:: Exporting to @LaTeX{}, and processing to PDF
2301 * DocBook export:: Exporting to DocBook
2302 * iCalendar export::
2305 @node Export options, The export dispatcher, Exporting, Exporting
2306 @section Export options
2308 The exporter recognizes special lines in the buffer which provide
2309 additional information. These lines may be put anywhere in the file.
2310 The whole set of lines can be inserted into the buffer with @kbd{C-c
2315 Insert template with export options, see example below.
2319 #+TITLE: the title to be shown (default is the buffer name)
2320 #+AUTHOR: the author (default taken from @code{user-full-name})
2321 #+DATE: a date, fixed, of a format string for @code{format-time-string}
2322 #+EMAIL: his/her email address (default from @code{user-mail-address})
2323 #+DESCRIPTION: the page description, e.g.@: for the XHTML meta tag
2324 #+KEYWORDS: the page keywords, e.g.@: for the XHTML meta tag
2325 #+LANGUAGE: language for HTML, e.g.@: @samp{en} (@code{org-export-default-language})
2326 #+TEXT: Some descriptive text to be inserted at the beginning.
2327 #+TEXT: Several lines may be given.
2328 #+OPTIONS: H:2 num:t toc:t \n:nil @@:t ::t |:t ^:t f:t TeX:t ...
2329 #+LINK_UP: the ``up'' link of an exported page
2330 #+LINK_HOME: the ``home'' link of an exported page
2331 #+LATEX_HEADER: extra line(s) for the @LaTeX{} header, like \usepackage@{xyz@}
2334 @node The export dispatcher, ASCII/Latin-1/UTF-8 export, Export options, Exporting
2335 @section The export dispatcher
2337 All export commands can be reached using the export dispatcher, which is a
2338 prefix key that prompts for an additional key specifying the command.
2339 Normally the entire file is exported, but if there is an active region that
2340 contains one outline tree, the first heading is used as document title and
2341 the subtrees are exported.
2345 Dispatcher for export and publishing commands.
2348 @node ASCII/Latin-1/UTF-8 export, HTML export, The export dispatcher, Exporting
2349 @section ASCII/Latin-1/UTF-8 export
2351 ASCII export produces a simple and very readable version of an Org-mode
2352 file, containing only plain ASCII. Latin-1 and UTF-8 export augment the file
2353 with special characters and symbols available in these encodings.
2357 Export as ASCII file.
2358 @item C-c C-e n @ @ @r{and} @ @ C-c C-e N
2359 Like the above commands, but use Latin-1 encoding.
2360 @item C-c C-e u @ @ @r{and} @ @ C-c C-e U
2361 Like the above commands, but use UTF-8 encoding.
2364 @node HTML export, @LaTeX{} and PDF export, ASCII/Latin-1/UTF-8 export, Exporting
2365 @section HTML export
2369 Export as HTML file @file{myfile.html}.
2371 Export as HTML file and immediately open it with a browser.
2374 To insert HTML that should be copied verbatim to
2375 the exported file use either
2378 #+HTML: Literal HTML code for export
2383 All lines between these markers are exported literally
2387 @node @LaTeX{} and PDF export, DocBook export, HTML export, Exporting
2388 @section @LaTeX{} and PDF export
2392 Export as @LaTeX{} file @file{myfile.tex}.
2394 Export as @LaTeX{} and then process to PDF.
2396 Export as @LaTeX{} and then process to PDF, then open the resulting PDF file.
2399 By default, the @LaTeX{} output uses the class @code{article}. You can
2400 change this by adding an option like @code{#+LaTeX_CLASS: myclass} in your
2401 file. The class must be listed in @code{org-export-latex-classes}.
2403 Embedded @LaTeX{} as described in @ref{Embedded @LaTeX{}}, will be correctly
2404 inserted into the @LaTeX{} file. Similarly to the HTML exporter, you can use
2405 @code{#+LaTeX:} and @code{#+BEGIN_LaTeX ... #+END_LaTeX} construct to add
2406 verbatim @LaTeX{} code.
2408 @node DocBook export, iCalendar export, @LaTeX{} and PDF export, Exporting
2409 @section DocBook export
2413 Export as DocBook file.
2416 Similarly to the HTML exporter, you can use @code{#+DOCBOOK:} and
2417 @code{#+BEGIN_DOCBOOK ... #+END_DOCBOOK} construct to add verbatim @LaTeX{}
2420 @node iCalendar export, , DocBook export, Exporting
2421 @section iCalendar export
2425 Create iCalendar entries for the current file in a @file{.ics} file.
2427 Create a single large iCalendar file from all files in
2428 @code{org-agenda-files} and write it to the file given by
2429 @code{org-combined-agenda-icalendar-file}.
2433 @uref{http://orgmode.org/manual/Exporting.html#Exporting, Chapter 12 of the manual}@*
2434 @uref{http://orgmode.org/worg/org-tutorials/images-and-xhtml-export.php,
2435 Sebastian Rose's image handling tutorial}@*
2436 @uref{http://orgmode.org/worg/org-tutorials/org-latex-export.php, Thomas
2437 Dye's LaTeX export tutorial}
2438 @uref{http://orgmode.org/worg/org-tutorials/org-beamer/tutorial.php, Eric
2439 Fraga's BEAMER presentation tutorial}}
2441 @node Publishing, Working With Source Code, Exporting, Top
2444 Org includes a publishing management system that allows you to configure
2445 automatic HTML conversion of @emph{projects} composed of interlinked org
2446 files. You can also configure Org to automatically upload your exported HTML
2447 pages and related attachments, such as images and source code files, to a web
2448 server. For detailed instructions about setup, see the manual.
2453 (setq org-publish-project-alist
2455 :base-directory "~/org/"
2456 :publishing-directory "~/public_html"
2457 :section-numbers nil
2458 :table-of-contents nil
2459 :style "<link rel=\"stylesheet\"
2460 href=\"../other/mystyle.css\"
2461 type=\"text/css\"/>")))
2466 Prompt for a specific project and publish all files that belong to it.
2468 Publish the project containing the current file.
2470 Publish only the current file.
2472 Publish every project.
2475 Org uses timestamps to track when a file has changed. The above functions
2476 normally only publish changed files. You can override this and force
2477 publishing of all files by giving a prefix argument to any of the commands
2481 @uref{http://orgmode.org/manual/Publishing.html#Publishing, Chapter 13 of the
2483 @uref{http://orgmode.org/worg/org-tutorials/org-publish-html-tutorial.php,
2484 Sebastian Rose's publishing tutorial}@*
2485 @uref{http://orgmode.org/worg/org-tutorials/org-jekyll.php, Ian Barton's
2486 Jekyll/blogging setup}}
2488 @node Working With Source Code, Miscellaneous, Publishing, Top
2489 @chapter Working with source code
2490 Org-mode provides a number of features for working with source code,
2491 including editing of code blocks in their native major-mode, evaluation of
2492 code blocks, tangling of code blocks, and exporting code blocks and their
2493 results in several formats.
2495 @subheading Structure of Code Blocks
2496 The structure of code blocks is as follows:
2500 #+BEGIN_SRC <language> <switches> <header arguments>
2505 Where @code{<name>} is a string used to name the code block,
2506 @code{<language>} specifies the language of the code block
2507 (e.g.@: @code{emacs-lisp}, @code{shell}, @code{R}, @code{python}, etc...),
2508 @code{<switches>} can be used to control export of the code block,
2509 @code{<header arguments>} can be used to control many aspects of code block
2510 behavior as demonstrated below, and @code{<body>} contains the actual source
2513 @subheading Editing source code
2514 Use @kbd{C-c '} to edit the current code block. This brings up a language
2515 major-mode edit buffer containing the body of the code block. Saving this
2516 buffer will write the new contents back to the Org buffer. Use @kbd{C-c '}
2517 again to exit the edit buffer.
2519 @subheading Evaluating code blocks
2520 Use @kbd{C-c C-c} to evaluate the current code block and insert its results
2521 in the Org-mode buffer. By default, evaluation is only turned on for
2522 @code{emacs-lisp} code blocks, however support exists for evaluating blocks
2523 in many languages. For a complete list of supported languages see the
2524 manual. The following shows a code block and its results.
2527 #+BEGIN_SRC emacs-lisp
2535 @subheading Extracting source code
2536 Use @kbd{C-c C-v t} to create pure source code files by extracting code from
2537 source blocks in the current buffer. This is referred to as ``tangling''---a
2538 term adopted from the literate programming community. During ``tangling'' of
2539 code blocks their bodies are expanded using @code{org-babel-expand-src-block}
2540 which can expand both variable and ``noweb'' style references. In order to
2541 tangle a code block it must have a @code{:tangle} header argument, see the
2544 @subheading Library of Babel
2545 Use @kbd{C-c C-v l} to load the code blocks from an Org-mode files into the
2546 ``Library of Babel'', these blocks can then be evaluated from any Org-mode
2547 buffer. A collection of generally useful code blocks is distributed with
2548 Org-mode in @code{contrib/library-of-babel.org}.
2550 @subheading Header Arguments
2551 Many aspects of the evaluation and export of code blocks are controlled
2552 through header arguments. These can be specified globally, at the file
2553 level, at the outline subtree level, and at the individual code block level.
2554 The following describes some of the header arguments.
2557 The @code{:var} header argument is used to pass arguments to code blocks.
2558 The values passed to arguments can be literal values, values from org-mode
2559 tables and literal example blocks, or the results of other named code blocks.
2561 The @code{:results} header argument controls the @emph{collection},
2562 @emph{type}, and @emph{handling} of code block results. Values of
2563 @code{output} or @code{value} (the default) specify how results are collected
2564 from a code block's evaluation. Values of @code{vector}, @code{scalar}
2565 @code{file} @code{raw} @code{html} @code{latex} and @code{code} specify the
2566 type of the results of the code block which dictates how they will be
2567 incorporated into the Org-mode buffer. Values of @code{silent},
2568 @code{replace}, @code{prepend}, and @code{append} specify handling of code
2569 block results, specifically if and how the results should be inserted into
2570 the Org-mode buffer.
2572 A header argument of @code{:session} will cause the code block to be
2573 evaluated in a persistent interactive inferior process in Emacs. This allows
2574 for persisting state between code block evaluations, and for manual
2575 inspection of the results of evaluation.
2577 Any combination of the @emph{code} or the @emph{results} of a block can be
2578 retained on export, this is specified by setting the @code{:results} header
2579 argument to @code{code} @code{results} @code{none} or @code{both}.
2581 A header argument of @code{:tangle yes} will cause a code block's contents to
2582 be tangled to a file named after the filename of the Org-mode buffer. An
2583 alternate file name can be specified with @code{:tangle filename}.
2585 A header argument of @code{:cache yes} will cause associate a hash of the
2586 expanded code block with the results, ensuring that code blocks are only
2587 re-run when their inputs have changed.
2589 A header argument of @code{:noweb yes} will expand ``noweb'' style references
2590 on evaluation and tangling.
2592 Code blocks which output results to files (e.g.@: graphs, diagrams and figures)
2593 can accept a @code{:file filename} header argument in which case the results
2594 are saved to the named file, and a link to the file is inserted into the
2599 @uref{http://orgmode.org/manual/Literal-examples.html#Literal-examples,
2600 Chapter 11.3 of the manual}@*
2601 @uref{http://orgmode.org/worg/org-contrib/babel/index.php,
2602 The Babel site on Worg}}
2604 @node Miscellaneous, , Working With Source Code, Top
2605 @chapter Miscellaneous
2608 * Completion:: M-TAB knows what you need
2609 * Clean view:: Getting rid of leading stars in the outline
2610 * MobileOrg:: Org-mode on the iPhone
2613 @node Completion, Clean view, Miscellaneous, Miscellaneous
2616 Org supports in-buffer completion with @kbd{M-@key{TAB}}. This type of
2617 completion does not make use of the minibuffer. You simply type a few
2618 letters into the buffer and use the key to complete text right there. For
2619 example, this command will complete @TeX{} symbols after @samp{\}, TODO
2620 keywords at the beginning of a headline, and tags after @samp{:} in a
2623 @node Clean view, MobileOrg, Completion, Miscellaneous
2624 @section A cleaner outline view
2626 Some people find it noisy and distracting that the Org headlines start with a
2627 potentially large number of stars, and that text below the headlines is not
2628 indented. While this is no problem when writing a @emph{book-like} document
2629 where the outline headings are really section headings, in a more
2630 @emph{list-oriented} outline, indented structure is a lot cleaner:
2634 * Top level headline | * Top level headline
2635 ** Second level | * Second level
2636 *** 3rd level | * 3rd level
2637 some text | some text
2638 *** 3rd level | * 3rd level
2639 more text | more text
2640 * Another top level headline | * Another top level headline
2645 If you are using at least Emacs 23.1.50.3 and version 6.29 of Org, this kind
2646 of view can be achieved dynamically at display time using
2647 @code{org-indent-mode}, which will prepend intangible space to each line.
2648 You can turn on @code{org-indent-mode} for all files by customizing the
2649 variable @code{org-startup-indented}, or you can turn it on for individual
2656 If you want a similar effect in earlier version of Emacs and/or Org, or if
2657 you want the indentation to be hard space characters so that the plain text
2658 file looks as similar as possible to the Emacs display, Org supports you by
2659 helping to indent (with @key{TAB}) text below each headline, by hiding
2660 leading stars, and by only using levels 1, 3, etc to get two characters
2661 indentation for each level. To get this support in a file, use
2664 #+STARTUP: hidestars odd
2667 @node MobileOrg, , Clean view, Miscellaneous
2670 @i{MobileOrg} is the name of the mobile companion app for Org mode, currently
2671 available for iOS and for Android. @i{MobileOrg} offers offline viewing and
2672 capture support for an Org mode system rooted on a ``real'' computer. It
2673 does also allow you to record changes to existing entries.
2675 The @uref{http://mobileorg.ncogni.to/, iOS implementation} for the
2676 @i{iPhone/iPod Touch/iPad} series of devices, was developed by Richard
2677 Moreland. Android users should check out
2678 @uref{http://wiki.github.com/matburt/mobileorg-android/, MobileOrg Android}
2679 by Matt Jones. The two implementations are not identical but offer similar
2683 @uref{http://orgmode.org/manual/Miscellaneous.html#Miscellaneous, Chapter 15
2685 @uref{http://orgmode.org/manual/MobileOrg.html#MobileOrg, Appendix B of the
2687 @uref{http://orgmode.org/orgcard.pdf,Key reference card}}
2696 @c LocalWords: webdavhost pre