3 @setfilename ../../info/orgguide
4 @settitle The compact Org-mode Guide
6 @include org-version.inc
8 @c Use proper quote and backtick for code sections in PDF output
9 @c Cf. Texinfo manual 14.2
10 @set txicodequoteundirected
11 @set txicodequotebacktick
13 @c Version and Contact Info
14 @set MAINTAINERSITE @uref{http://orgmode.org,maintainers webpage}
15 @set AUTHOR Carsten Dominik
16 @set MAINTAINER Bastien Guerry
17 @set MAINTAINEREMAIL @email{bzg at gnu dot org}
18 @set MAINTAINERCONTACT @uref{mailto:bzg at gnu dot org,contact the maintainer}
24 @c @hyphenation{time-stamp time-stamps time-stamp-ing time-stamp-ed}
27 @c Subheadings inside a table.
28 @macro tsubheading{text}
38 @noindent @b{Further reading}@*@noindent \text\
42 Copyright @copyright{} 2010--2013 Free Software Foundation
45 Permission is granted to copy, distribute and/or modify this document
46 under the terms of the GNU Free Documentation License, Version 1.3 or
47 any later version published by the Free Software Foundation; with no
48 Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
49 and with the Back-Cover Texts as in (a) below. A copy of the license
50 is included in the section entitled ``GNU Free Documentation License.''
52 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
53 modify this GNU manual.''
59 * Org Mode Guide: (orgguide). Abbreviated Org-mode Manual
63 @title The compact Org-mode Guide
65 @subtitle Release @value{VERSION}
66 @author by Carsten Dominik
68 @c The following two commands start the copyright page.
70 @vskip 0pt plus 1filll
74 @c Output the table of contents at the beginning.
78 @node Top, Introduction, (dir), (dir)
85 * Introduction:: Getting started
86 * Document Structure:: A tree works like your brain
87 * Tables:: Pure magic for quick formatting
88 * Hyperlinks:: Notes in context
89 * TODO Items:: Every tree branch can be a TODO item
90 * Tags:: Tagging headlines and matching sets of tags
91 * Properties:: Properties
92 * Dates and Times:: Making items useful for planning
93 * Capture - Refile - Archive:: The ins and outs for projects
94 * Agenda Views:: Collecting information into views
95 * Markup:: Prepare text for rich export
96 * Exporting:: Sharing and publishing of notes
97 * Publishing:: Create a web site of linked Org files
98 * Working With Source Code:: Source code snippets embedded in Org
99 * Miscellaneous:: All the rest which did not fit elsewhere
101 * GNU Free Documentation License:: This manual license.
104 --- The Detailed Node Listing ---
109 * Installation:: How to install a downloaded version of Org
110 * Activation:: How to activate Org for certain buffers
111 * Feedback:: Bug reports, ideas, patches etc.
115 * Outlines:: Org is based on Outline mode
116 * Headlines:: How to typeset Org tree headlines
117 * Visibility cycling:: Show and hide, much simplified
118 * Motion:: Jumping to other headlines
119 * Structure editing:: Changing sequence and level of headlines
120 * Sparse trees:: Matches embedded in context
121 * Plain lists:: Additional structure within an entry
122 * Footnotes:: How footnotes are defined in Org's syntax
126 * Link format:: How links in Org are formatted
127 * Internal links:: Links to other places in the current file
128 * External links:: URL-like links to the world
129 * Handling links:: Creating, inserting and following
130 * Targeted links:: Point at a location in a file
134 * Using TODO states:: Setting and switching states
135 * Multi-state workflows:: More than just on/off
136 * Progress logging:: Dates and notes for progress
137 * Priorities:: Some things are more important than others
138 * Breaking down tasks:: Splitting a task into manageable pieces
139 * Checkboxes:: Tick-off lists
143 * Closing items:: When was this entry marked DONE?
144 * Tracking TODO state changes:: When did the status change?
148 * Tag inheritance:: Tags use the tree structure of the outline
149 * Setting tags:: How to assign tags to a headline
150 * Tag searches:: Searching for combinations of tags
154 * Timestamps:: Assigning a time to a tree entry
155 * Creating timestamps:: Commands which insert timestamps
156 * Deadlines and scheduling:: Planning your work
157 * Clocking work time:: Tracking how long you spend on a task
159 Capture - Refile - Archive
162 * Refile and copy:: Moving a tree from one place to another
163 * Archiving:: What to do with finished projects
167 * Setting up a capture location:: Where notes will be stored
168 * Using capture:: Commands to invoke and terminate capture
169 * Capture templates:: Define the outline of different note types
173 * Agenda files:: Files being searched for agenda information
174 * Agenda dispatcher:: Keyboard access to agenda views
175 * Built-in agenda views:: What is available out of the box?
176 * Agenda commands:: Remote editing of Org trees
177 * Custom agenda views:: Defining special searches and views
179 The built-in agenda views
181 * Weekly/daily agenda:: The calendar page with current tasks
182 * Global TODO list:: All unfinished action items
183 * Matching tags and properties:: Structured information with fine-tuned search
184 * Timeline:: Time-sorted view for single file
185 * Search view:: Find entries by searching for text
187 Markup for rich export
189 * Structural markup elements:: The basic structure as seen by the exporter
190 * Images and tables:: Tables and Images will be included
191 * Literal examples:: Source code examples with special formatting
192 * Include files:: Include additional files into a document
193 * Embedded @LaTeX{}:: @LaTeX{} can be freely used inside Org documents
195 Structural markup elements
197 * Document title:: Where the title is taken from
198 * Headings and sections:: The document structure as seen by the exporter
199 * Table of contents:: The if and where of the table of contents
200 * Paragraphs:: Paragraphs
201 * Emphasis and monospace:: Bold, italic, etc.
202 * Comment lines:: What will *not* be exported
206 * Export options:: Per-file export settings
207 * The export dispatcher:: How to access exporter commands
208 * ASCII/Latin-1/UTF-8 export:: Exporting to flat files with encoding
209 * HTML export:: Exporting to HTML
210 * @LaTeX{} and PDF export:: Exporting to @LaTeX{}, and processing to PDF
211 * DocBook export:: Exporting to DocBook
216 * Completion:: M-TAB knows what you need
217 * Clean view:: Getting rid of leading stars in the outline
218 * MobileOrg:: Org-mode on the iPhone
223 @node Introduction, Document Structure, Top, Top
224 @chapter Introduction
228 * Installation:: How to install a downloaded version of Org
229 * Activation:: How to activate Org for certain buffers
230 * Feedback:: Bug reports, ideas, patches etc.
233 @node Preface, Installation, Introduction, Introduction
236 Org is a mode for keeping notes, maintaining TODO lists, and doing project
237 planning with a fast and effective plain-text system. It is also an
238 authoring and publishing system.
240 @i{This document is a much compressed derivative of the
241 @uref{http://orgmode.org/index.html#sec-4_1, comprehensive Org-mode manual}.
242 It contains all basic features and commands, along with important hints for
243 customization. It is intended for beginners who would shy back from a 200
244 page manual because of sheer size.}
246 @node Installation, Activation, Preface, Introduction
247 @section Installation
249 @b{Important:} @i{If you are using a version of Org that is part of the Emacs
250 distribution or an XEmacs package, please skip this section and go directly
251 to @ref{Activation}.}
253 If you have downloaded Org from the Web, either as a distribution @file{.zip}
254 or @file{.tar} file, or as a Git archive, it is best to run it directly from
255 the distribution directory. You need to add the @file{lisp} subdirectories
256 to the Emacs load path. To do this, add the following line to @file{.emacs}:
259 (setq load-path (cons "~/path/to/orgdir/lisp" load-path))
260 (setq load-path (cons "~/path/to/orgdir/contrib/lisp" load-path))
263 @noindent For speed you should byte-compile the Lisp files with the shell
270 @node Activation, Feedback, Installation, Introduction
273 Add the following lines to your @file{.emacs} file. The last three lines
274 define @emph{global} keys for some commands --- please choose suitable keys
278 ;; The following lines are always needed. Choose your own keys.
279 (add-to-list 'auto-mode-alist '("\\.org\\'" . org-mode)) ; not needed since Emacs 22.2
280 (add-hook 'org-mode-hook 'turn-on-font-lock) ; not needed when global-font-lock-mode is on
281 (global-set-key "\C-cl" 'org-store-link)
282 (global-set-key "\C-ca" 'org-agenda)
283 (global-set-key "\C-cb" 'org-iswitchb)
286 With this setup, all files with extension @samp{.org} will be put
289 @node Feedback, , Activation, Introduction
292 If you find problems with Org, or if you have questions, remarks, or ideas
293 about it, please mail to the Org mailing list @email{emacs-orgmode@@gnu.org}.
294 For information on how to submit bug reports, see the main manual.
296 @node Document Structure, Tables, Introduction, Top
297 @chapter Document Structure
299 Org is based on Outline mode and provides flexible commands to
300 edit the structure of the document.
303 * Outlines:: Org is based on Outline mode
304 * Headlines:: How to typeset Org tree headlines
305 * Visibility cycling:: Show and hide, much simplified
306 * Motion:: Jumping to other headlines
307 * Structure editing:: Changing sequence and level of headlines
308 * Sparse trees:: Matches embedded in context
309 * Plain lists:: Additional structure within an entry
310 * Footnotes:: How footnotes are defined in Org's syntax
313 @node Outlines, Headlines, Document Structure, Document Structure
316 Org is implemented on top of Outline mode. Outlines allow a
317 document to be organized in a hierarchical structure, which (at least
318 for me) is the best representation of notes and thoughts. An overview
319 of this structure is achieved by folding (hiding) large parts of the
320 document to show only the general document structure and the parts
321 currently being worked on. Org greatly simplifies the use of
322 outlines by compressing the entire show/hide functionality into a single
323 command, @command{org-cycle}, which is bound to the @key{TAB} key.
325 @node Headlines, Visibility cycling, Outlines, Document Structure
328 Headlines define the structure of an outline tree. The headlines in
329 Org start with one or more stars, on the left margin@footnote{See
330 the variable @code{org-special-ctrl-a/e} to configure special behavior
331 of @kbd{C-a} and @kbd{C-e} in headlines.}. For example:
341 * Another top level headline
344 @noindent Some people find the many stars too noisy and would prefer an
345 outline that has whitespace followed by a single star as headline
346 starters. @ref{Clean view}, describes a setup to realize this.
348 @node Visibility cycling, Motion, Headlines, Document Structure
349 @section Visibility cycling
351 Outlines make it possible to hide parts of the text in the buffer.
352 Org uses just two commands, bound to @key{TAB} and
353 @kbd{S-@key{TAB}} to change the visibility in the buffer.
357 @emph{Subtree cycling}: Rotate current subtree among the states
360 ,-> FOLDED -> CHILDREN -> SUBTREE --.
361 '-----------------------------------'
364 When called with a prefix argument (@kbd{C-u @key{TAB}}) or with the shift
365 key, global cycling is invoked.
367 @item S-@key{TAB} @r{and} C-u @key{TAB}
368 @emph{Global cycling}: Rotate the entire buffer among the states
371 ,-> OVERVIEW -> CONTENTS -> SHOW ALL --.
372 '--------------------------------------'
375 @item C-u C-u C-u @key{TAB}
376 Show all, including drawers.
379 When Emacs first visits an Org file, the global state is set to
380 OVERVIEW, i.e.@: only the top level headlines are visible. This can be
381 configured through the variable @code{org-startup-folded}, or on a
382 per-file basis by adding a startup keyword @code{overview}, @code{content},
383 @code{showall}, like this:
390 @node Motion, Structure editing, Visibility cycling, Document Structure
392 The following commands jump to other headlines in the buffer.
400 Next heading same level.
402 Previous heading same level.
404 Backward to higher level heading.
407 @node Structure editing, Sparse trees, Motion, Document Structure
408 @section Structure editing
412 Insert new heading with same level as current. If the cursor is in a plain
413 list item, a new item is created (@pxref{Plain lists}). When this command is
414 used in the middle of a line, the line is split and the rest of the line
415 becomes the new headline@footnote{If you do not want the line to be split,
416 customize the variable @code{org-M-RET-may-split-line}.}.
418 Insert new TODO entry with same level as current heading.
419 @item @key{TAB} @r{in new, empty entry}
420 In a new entry with no text yet, @key{TAB} will cycle through reasonable
422 @item M-@key{left}@r{/}@key{right}
423 Promote/demote current heading by one level.
424 @item M-S-@key{left}@r{/}@key{right}
425 Promote/demote the current subtree by one level.
426 @item M-S-@key{up}@r{/}@key{down}
427 Move subtree up/down (swap with previous/next subtree of same
430 Refile entry or region to a different location. @xref{Refile and copy}.
432 Narrow buffer to current subtree / widen it again
435 When there is an active region (Transient Mark mode), promotion and
436 demotion work on all headlines in the region.
438 @node Sparse trees, Plain lists, Structure editing, Document Structure
439 @section Sparse trees
441 An important feature of Org mode is the ability to construct @emph{sparse
442 trees} for selected information in an outline tree, so that the entire
443 document is folded as much as possible, but the selected information is made
444 visible along with the headline structure above it@footnote{See also the
445 variables @code{org-show-hierarchy-above}, @code{org-show-following-heading},
446 @code{org-show-siblings}, and @code{org-show-entry-below} for detailed
447 control on how much context is shown around each match.}. Just try it out
448 and you will see immediately how it works.
450 Org mode contains several commands creating such trees, all these
451 commands can be accessed through a dispatcher:
455 This prompts for an extra key to select a sparse-tree creating command.
457 Occur. Prompts for a regexp and shows a sparse tree with all matches. Each
458 match is also highlighted; the highlights disappear by pressing @kbd{C-c C-c}.
461 The other sparse tree commands select headings based on TODO keywords,
462 tags, or properties and will be discussed later in this manual.
464 @node Plain lists, Footnotes, Sparse trees, Document Structure
467 Within an entry of the outline tree, hand-formatted lists can provide
468 additional structure. They also provide a way to create lists of
469 checkboxes (@pxref{Checkboxes}). Org supports editing such lists,
470 and the HTML exporter (@pxref{Exporting}) parses and formats them.
472 Org knows ordered lists, unordered lists, and description lists.
475 @emph{Unordered} list items start with @samp{-}, @samp{+}, or
478 @emph{Ordered} list items start with @samp{1.} or @samp{1)}.
480 @emph{Description} list use @samp{ :: } to separate the @emph{term} from the
484 Items belonging to the same list must have the same indentation on the first
485 line. An item ends before the next line that is indented like its
486 bullet/number, or less. A list ends when all items are closed, or before two
487 blank lines. An example:
492 My favorite scenes are (in this order)
493 1. The attack of the Rohirrim
494 2. Eowyn's fight with the witch king
495 + this was already my favorite scene in the book
496 + I really like Miranda Otto.
497 Important actors in this film are:
498 - @b{Elijah Wood} :: He plays Frodo
499 - @b{Sean Austin} :: He plays Sam, Frodo's friend.
503 The following commands act on items when the cursor is in the first line of
504 an item (the line with the bullet or number).
508 Items can be folded just like headline levels.
510 Insert new item at current level. With a prefix argument, force a new
511 heading (@pxref{Structure editing}).
513 Insert a new item with a checkbox (@pxref{Checkboxes}).
514 @item M-S-@key{up}@r{/}@key{down}
515 Move the item including subitems up/down (swap with previous/next item
516 of same indentation). If the list is ordered, renumbering is
518 @item M-@key{left}@r{/}M-@key{right}
519 Decrease/increase the indentation of an item, leaving children alone.
520 @item M-S-@key{left}@r{/}@key{right}
521 Decrease/increase the indentation of the item, including subitems.
523 If there is a checkbox (@pxref{Checkboxes}) in the item line, toggle the
524 state of the checkbox. Also verify bullets and indentation consistency in
527 Cycle the entire list level through the different itemize/enumerate bullets
528 (@samp{-}, @samp{+}, @samp{*}, @samp{1.}, @samp{1)}).
531 @node Footnotes, , Plain lists, Document Structure
534 A footnote is defined in a paragraph that is started by a footnote marker in
535 square brackets in column 0, no indentation allowed. The footnote reference
536 is simply the marker in square brackets, inside text. For example:
539 The Org homepage[fn:1] now looks a lot better than it used to.
541 [fn:1] The link is: http://orgmode.org
544 @noindent The following commands handle footnotes:
548 The footnote action command. When the cursor is on a footnote reference,
549 jump to the definition. When it is at a definition, jump to the (first)
550 reference. Otherwise, create a new footnote. When this command is called
551 with a prefix argument, a menu of additional options including renumbering is
555 Jump between definition and reference.
559 @uref{http://orgmode.org/manual/Document-Structure.html#Document-Structure,
560 Chapter 2 of the manual}@*
561 @uref{http://sachachua.com/wp/2008/01/outlining-your-notes-with-org/,
562 Sacha Chua's tutorial}}
565 @node Tables, Hyperlinks, Document Structure, Top
568 Org comes with a fast and intuitive table editor. Spreadsheet-like
569 calculations are supported in connection with the Emacs @file{calc}
572 (@pxref{Top,Calc,,Calc,Gnu Emacs Calculator Manual}).
575 (see the Emacs Calculator manual for more information about the Emacs
579 Org makes it easy to format tables in plain ASCII. Any line with
580 @samp{|} as the first non-whitespace character is considered part of a
581 table. @samp{|} is also the column separator. A table might look like
585 | Name | Phone | Age |
586 |-------+-------+-----|
587 | Peter | 1234 | 17 |
591 A table is re-aligned automatically each time you press @key{TAB} or
592 @key{RET} or @kbd{C-c C-c} inside the table. @key{TAB} also moves to
593 the next field (@key{RET} to the next row) and creates new table rows
594 at the end of the table or before horizontal lines. The indentation
595 of the table is set by the first line. Any line starting with
596 @samp{|-} is considered as a horizontal separator line and will be
597 expanded on the next re-align to span the whole table width. So, to
598 create the above table, you would only type
605 @noindent and then press @key{TAB} to align the table and start filling in
606 fields. Even faster would be to type @code{|Name|Phone|Age} followed by
609 When typing text into a field, Org treats @key{DEL},
610 @key{Backspace}, and all character keys in a special way, so that
611 inserting and deleting avoids shifting other fields. Also, when
612 typing @emph{immediately after the cursor was moved into a new field
613 with @kbd{@key{TAB}}, @kbd{S-@key{TAB}} or @kbd{@key{RET}}}, the
614 field is automatically made blank.
617 @tsubheading{Creation and conversion}
619 Convert the active region to table. If every line contains at least one TAB
620 character, the function assumes that the material is tab separated. If every
621 line contains a comma, comma-separated values (CSV) are assumed. If not,
622 lines are split at whitespace into fields.
624 If there is no active region, this command creates an empty Org
625 table. But it's easier just to start typing, like
626 @kbd{|Name|Phone|Age C-c @key{RET}}.
628 @tsubheading{Re-aligning and field motion}
630 Re-align the table without moving the cursor.
633 Re-align the table, move to the next field. Creates a new row if
637 Re-align, move to previous field.
640 Re-align the table and move down to next row. Creates a new row if
643 @tsubheading{Column and row editing}
646 Move the current column left/right.
649 Kill the current column.
651 @item M-S-@key{right}
652 Insert a new column to the left of the cursor position.
656 Move the current row up/down.
659 Kill the current row or horizontal line.
662 Insert a new row above the current row. With a prefix argument, the line is
663 created below the current one.
666 Insert a horizontal line below current row. With a prefix argument, the line
667 is created above the current line.
670 Insert a horizontal line below current row, and move the cursor into the row
674 Sort the table lines in the region. The position of point indicates the
675 column to be used for sorting, and the range of lines is the range
676 between the nearest horizontal separator lines, or the entire table.
681 @uref{http://orgmode.org/manual/Tables.html#Tables, Chapter 3 of the
683 @uref{http://orgmode.org/worg/org-tutorials/tables.php, Bastien's
685 @uref{http://orgmode.org/worg/org-tutorials/org-spreadsheet-intro.php,
686 Bastien's spreadsheet tutorial}@*
687 @uref{http://orgmode.org/worg/org-tutorials/org-plot.php, Eric's plotting tutorial}}
689 @node Hyperlinks, TODO Items, Tables, Top
692 Like HTML, Org provides links inside a file, external links to
693 other files, Usenet articles, emails, and much more.
696 * Link format:: How links in Org are formatted
697 * Internal links:: Links to other places in the current file
698 * External links:: URL-like links to the world
699 * Handling links:: Creating, inserting and following
700 * Targeted links:: Point at a location in a file
703 @node Link format, Internal links, Hyperlinks, Hyperlinks
706 Org will recognize plain URL-like links and activate them as
707 clickable links. The general link format, however, looks like this:
710 [[link][description]] @r{or alternatively} [[link]]
714 Once a link in the buffer is complete (all brackets present), Org will change
715 the display so that @samp{description} is displayed instead of
716 @samp{[[link][description]]} and @samp{link} is displayed instead of
717 @samp{[[link]]}. To edit the invisible @samp{link} part, use @kbd{C-c
718 C-l} with the cursor on the link.
720 @node Internal links, External links, Link format, Hyperlinks
721 @section Internal links
723 If the link does not look like a URL, it is considered to be internal in the
724 current file. The most important case is a link like
725 @samp{[[#my-custom-id]]} which will link to the entry with the
726 @code{CUSTOM_ID} property @samp{my-custom-id}.
728 Links such as @samp{[[My Target]]} or @samp{[[My Target][Find my target]]}
729 lead to a text search in the current file for the corresponding target which
730 looks like @samp{<<My Target>>}.
732 @node External links, Handling links, Internal links, Hyperlinks
733 @section External links
735 Org supports links to files, websites, Usenet and email messages,
736 BBDB database entries and links to both IRC conversations and their
737 logs. External links are URL-like locators. They start with a short
738 identifying string followed by a colon. There can be no space after
739 the colon. Here are some examples:
742 http://www.astro.uva.nl/~dominik @r{on the web}
743 file:/home/dominik/images/jupiter.jpg @r{file, absolute path}
744 /home/dominik/images/jupiter.jpg @r{same as above}
745 file:papers/last.pdf @r{file, relative path}
746 file:projects.org @r{another Org file}
747 docview:papers/last.pdf::NNN @r{open file in doc-view mode at page NNN}
748 id:B7423F4D-2E8A-471B-8810-C40F074717E9 @r{Link to heading by ID}
749 news:comp.emacs @r{Usenet link}
750 mailto:adent@@galaxy.net @r{Mail link}
751 vm:folder @r{VM folder link}
752 vm:folder#id @r{VM message link}
753 wl:folder#id @r{WANDERLUST message link}
754 mhe:folder#id @r{MH-E message link}
755 rmail:folder#id @r{RMAIL message link}
756 gnus:group#id @r{Gnus article link}
757 bbdb:R.*Stallman @r{BBDB link (with regexp)}
758 irc:/irc.com/#emacs/bob @r{IRC link}
759 info:org:External%20links @r{Info node link (with encoded space)}
762 A link should be enclosed in double brackets and may contain a
763 descriptive text to be displayed instead of the URL (@pxref{Link
764 format}), for example:
767 [[http://www.gnu.org/software/emacs/][GNU Emacs]]
771 If the description is a file name or URL that points to an image, HTML export
772 (@pxref{HTML export}) will inline the image as a clickable button. If there
773 is no description at all and the link points to an image, that image will be
774 inlined into the exported HTML file.
776 @node Handling links, Targeted links, External links, Hyperlinks
777 @section Handling links
779 Org provides methods to create a link in the correct syntax, to
780 insert it into an Org file, and to follow the link.
784 Store a link to the current location. This is a @emph{global} command (you
785 must create the key binding yourself) which can be used in any buffer to
786 create a link. The link will be stored for later insertion into an Org
790 Insert a link. This prompts for a link to be inserted into the buffer. You
791 can just type a link, or use history keys @key{up} and @key{down} to access
792 stored links. You will be prompted for the description part of the link.
793 When called with a @kbd{C-u} prefix argument, file name completion is used to
796 @item C-c C-l @r{(with cursor on existing link)}
797 When the cursor is on an existing link, @kbd{C-c C-l} allows you to edit the
798 link and description parts of the link.
800 @item C-c C-o @r{or} mouse-1 @r{or} mouse-2
803 Jump back to a recorded position. A position is recorded by the
804 commands following internal links, and by @kbd{C-c %}. Using this
805 command several times in direct succession moves through a ring of
806 previously recorded positions.
810 @node Targeted links, , Handling links, Hyperlinks
811 @section Targeted links
813 File links can contain additional information to make Emacs jump to a
814 particular location in the file when following a link. This can be a
815 line number or a search option after a double colon.
817 Here is the syntax of the different ways to attach a search to a file
818 link, together with an explanation:
821 [[file:~/code/main.c::255]] @r{Find line 255}
822 [[file:~/xx.org::My Target]] @r{Find @samp{<<My Target>>}}
823 [[file:~/xx.org::#my-custom-id]] @r{Find entry with custom id}
827 @uref{http://orgmode.org/manual/Hyperlinks.html#Hyperlinks, Chapter 4 of the
830 @node TODO Items, Tags, Hyperlinks, Top
833 Org mode does not maintain TODO lists as separate documents@footnote{Of
834 course, you can make a document that contains only long lists of TODO items,
835 but this is not required.}. Instead, TODO items are an integral part of the
836 notes file, because TODO items usually come up while taking notes! With Org
837 mode, simply mark any entry in a tree as being a TODO item. In this way,
838 information is not duplicated, and the entire context from which the TODO
839 item emerged is always present.
841 Of course, this technique for managing TODO items scatters them
842 throughout your notes file. Org mode compensates for this by providing
843 methods to give you an overview of all the things that you have to do.
846 * Using TODO states:: Setting and switching states
847 * Multi-state workflows:: More than just on/off
848 * Progress logging:: Dates and notes for progress
849 * Priorities:: Some things are more important than others
850 * Breaking down tasks:: Splitting a task into manageable pieces
851 * Checkboxes:: Tick-off lists
854 @node Using TODO states, Multi-state workflows, TODO Items, TODO Items
855 @section Using TODO states
857 Any headline becomes a TODO item when it starts with the word
858 @samp{TODO}, for example:
861 *** TODO Write letter to Sam Fortune
865 The most important commands to work with TODO entries are:
869 Rotate the TODO state of the current item among
872 ,-> (unmarked) -> TODO -> DONE --.
873 '--------------------------------'
876 The same rotation can also be done ``remotely'' from the timeline and
877 agenda buffers with the @kbd{t} command key (@pxref{Agenda commands}).
879 @item S-@key{right}@r{/}@key{left}
880 Select the following/preceding TODO state, similar to cycling.
882 View TODO items in a @emph{sparse tree} (@pxref{Sparse trees}). Folds the
883 buffer, but shows all TODO items and the headings hierarchy above
886 Show the global TODO list. Collects the TODO items from all agenda files
887 (@pxref{Agenda Views}) into a single buffer. @xref{Global TODO list}, for
890 Insert a new TODO entry below the current one.
894 Changing a TODO state can also trigger tag changes. See the docstring of the
895 option @code{org-todo-state-tags-triggers} for details.
897 @node Multi-state workflows, Progress logging, Using TODO states, TODO Items
898 @section Multi-state workflows
900 You can use TODO keywords to indicate different @emph{sequential} states
901 in the process of working on an item, for example:
904 (setq org-todo-keywords
905 '((sequence "TODO" "FEEDBACK" "VERIFY" "|" "DONE" "DELEGATED")))
908 The vertical bar separates the TODO keywords (states that @emph{need
909 action}) from the DONE states (which need @emph{no further action}). If
910 you don't provide the separator bar, the last state is used as the DONE
912 With this setup, the command @kbd{C-c C-t} will cycle an entry from TODO
913 to FEEDBACK, then to VERIFY, and finally to DONE and DELEGATED.
915 Sometimes you may want to use different sets of TODO keywords in
916 parallel. For example, you may want to have the basic
917 @code{TODO}/@code{DONE}, but also a workflow for bug fixing, and a
918 separate state indicating that an item has been canceled (so it is not
919 DONE, but also does not require action). Your setup would then look
923 (setq org-todo-keywords
924 '((sequence "TODO(t)" "|" "DONE(d)")
925 (sequence "REPORT(r)" "BUG(b)" "KNOWNCAUSE(k)" "|" "FIXED(f)")
926 (sequence "|" "CANCELED(c)")))
929 The keywords should all be different, this helps Org mode to keep track of
930 which subsequence should be used for a given entry. The example also shows
931 how to define keys for fast access of a particular state, by adding a letter
932 in parenthesis after each keyword---you will be prompted for the key after
935 To define TODO keywords that are valid only in a single file, use the
936 following text anywhere in the file.
939 #+TODO: TODO(t) | DONE(d)
940 #+TODO: REPORT(r) BUG(b) KNOWNCAUSE(k) | FIXED(f)
941 #+TODO: | CANCELED(c)
944 After changing one of these lines, use @kbd{C-c C-c} with the cursor still in
945 the line to make the changes known to Org mode.
947 @node Progress logging, Priorities, Multi-state workflows, TODO Items
948 @section Progress logging
950 Org mode can automatically record a timestamp and possibly a note when
951 you mark a TODO item as DONE, or even each time you change the state of
952 a TODO item. This system is highly configurable; settings can be on a
953 per-keyword basis and can be localized to a file or even a subtree. For
954 information on how to clock working time for a task, see @ref{Clocking
958 * Closing items:: When was this entry marked DONE?
959 * Tracking TODO state changes:: When did the status change?
962 @node Closing items, Tracking TODO state changes, Progress logging, Progress logging
963 @unnumberedsubsec Closing items
965 The most basic logging is to keep track of @emph{when} a certain TODO
966 item was finished. This is achieved with@footnote{The corresponding
967 in-buffer setting is: @code{#+STARTUP: logdone}}.
970 (setq org-log-done 'time)
974 Then each time you turn an entry from a TODO (not-done) state into any of the
975 DONE states, a line @samp{CLOSED: [timestamp]} will be inserted just after
976 the headline. If you want to record a note along with the timestamp,
977 use@footnote{The corresponding in-buffer setting is: @code{#+STARTUP:
981 (setq org-log-done 'note)
985 You will then be prompted for a note, and that note will be stored below
986 the entry with a @samp{Closing Note} heading.
988 @node Tracking TODO state changes, , Closing items, Progress logging
989 @unnumberedsubsec Tracking TODO state changes
991 You might want to keep track of TODO state changes. You can either record
992 just a timestamp, or a time-stamped note for a change. These records will be
993 inserted after the headline as an itemized list. When taking a lot of notes,
994 you might want to get the notes out of the way into a drawer. Customize the
995 variable @code{org-log-into-drawer} to get this behavior.
997 For state logging, Org mode expects configuration on a per-keyword basis.
998 This is achieved by adding special markers @samp{!} (for a timestamp) and
999 @samp{@@} (for a note) in parentheses after each keyword. For example:
1001 #+TODO: TODO(t) WAIT(w@@/!) | DONE(d!) CANCELED(c@@)
1004 will define TODO keywords and fast access keys, and also request that a time
1005 is recorded when the entry is set to DONE, and that a note is recorded when
1006 switching to WAIT or CANCELED. The same syntax works also when setting
1007 @code{org-todo-keywords}.
1009 @node Priorities, Breaking down tasks, Progress logging, TODO Items
1012 If you use Org mode extensively, you may end up with enough TODO items that
1013 it starts to make sense to prioritize them. Prioritizing can be done by
1014 placing a @emph{priority cookie} into the headline of a TODO item, like this
1017 *** TODO [#A] Write letter to Sam Fortune
1021 Org mode supports three priorities: @samp{A}, @samp{B}, and @samp{C}.
1022 @samp{A} is the highest, @samp{B} the default if none is given. Priorities
1023 make a difference only in the agenda.
1027 Set the priority of the current headline. Press @samp{A}, @samp{B} or
1028 @samp{C} to select a priority, or @key{SPC} to remove the cookie.
1032 Increase/decrease priority of current headline
1035 @node Breaking down tasks, Checkboxes, Priorities, TODO Items
1036 @section Breaking tasks down into subtasks
1038 It is often advisable to break down large tasks into smaller, manageable
1039 subtasks. You can do this by creating an outline tree below a TODO item,
1040 with detailed subtasks on the tree. To keep the overview over the fraction
1041 of subtasks that are already completed, insert either @samp{[/]} or
1042 @samp{[%]} anywhere in the headline. These cookies will be updated each time
1043 the TODO status of a child changes, or when pressing @kbd{C-c C-c} on the
1044 cookie. For example:
1047 * Organize Party [33%]
1048 ** TODO Call people [1/2]
1052 ** DONE Talk to neighbor
1055 @node Checkboxes, , Breaking down tasks, TODO Items
1058 Every item in a plain list (@pxref{Plain lists}) can be made into a checkbox
1059 by starting it with the string @samp{[ ]}. Checkboxes are not included in
1060 the global TODO list, so they are often great to split a task into a number
1062 Here is an example of a checkbox list.
1065 * TODO Organize party [1/3]
1066 - [-] call people [1/2]
1070 - [ ] think about what music to play
1073 Checkboxes work hierarchically, so if a checkbox item has children that
1074 are checkboxes, toggling one of the children checkboxes will make the
1075 parent checkbox reflect if none, some, or all of the children are
1078 @noindent The following commands work with checkboxes:
1082 Toggle checkbox status or (with prefix arg) checkbox presence at point.
1084 Insert a new item with a checkbox.
1085 This works only if the cursor is already in a plain list item
1086 (@pxref{Plain lists}).
1090 @uref{http://orgmode.org/manual/TODO-Items.html#TODO-Items, Chapter 5 of the manual}@*
1091 @uref{http://orgmode.org/worg/org-tutorials/orgtutorial_dto.php, David
1092 O'Toole's introductory tutorial}@*
1093 @uref{http://members.optusnet.com.au/~charles57/GTD/gtd_workflow.html,
1094 Charles Cave's GTD setup}}
1096 @node Tags, Properties, TODO Items, Top
1099 An excellent way to implement labels and contexts for cross-correlating
1100 information is to assign @i{tags} to headlines. Org mode has extensive
1103 Every headline can contain a list of tags; they occur at the end of the
1104 headline. Tags are normal words containing letters, numbers, @samp{_}, and
1105 @samp{@@}. Tags must be preceded and followed by a single colon, e.g.,
1106 @samp{:work:}. Several tags can be specified, as in @samp{:work:urgent:}.
1107 Tags will by default be in bold face with the same color as the headline.
1110 * Tag inheritance:: Tags use the tree structure of the outline
1111 * Setting tags:: How to assign tags to a headline
1112 * Tag searches:: Searching for combinations of tags
1115 @node Tag inheritance, Setting tags, Tags, Tags
1116 @section Tag inheritance
1118 @i{Tags} make use of the hierarchical structure of outline trees. If a
1119 heading has a certain tag, all subheadings will inherit the tag as
1120 well. For example, in the list
1123 * Meeting with the French group :work:
1124 ** Summary by Frank :boss:notes:
1125 *** TODO Prepare slides for him :action:
1129 the final heading will have the tags @samp{:work:}, @samp{:boss:},
1130 @samp{:notes:}, and @samp{:action:} even though the final heading is not
1131 explicitly marked with those tags. You can also set tags that all entries in
1132 a file should inherit just as if these tags were defined in a hypothetical
1133 level zero that surrounds the entire file. Use a line like this@footnote{As
1134 with all these in-buffer settings, pressing @kbd{C-c C-c} activates any
1135 changes in the line.}:
1138 #+FILETAGS: :Peter:Boss:Secret:
1141 @node Setting tags, Tag searches, Tag inheritance, Tags
1142 @section Setting tags
1144 Tags can simply be typed into the buffer at the end of a headline.
1145 After a colon, @kbd{M-@key{TAB}} offers completion on tags. There is
1146 also a special command for inserting tags:
1150 Enter new tags for the current headline. Org mode will either offer
1151 completion or a special single-key interface for setting tags, see
1152 below. After pressing @key{RET}, the tags will be inserted and aligned
1153 to @code{org-tags-column}. When called with a @kbd{C-u} prefix, all
1154 tags in the current buffer will be aligned to that column, just to make
1157 When the cursor is in a headline, this does the same as @kbd{C-c C-q}.
1160 Org will support tag insertion based on a @emph{list of tags}. By
1161 default this list is constructed dynamically, containing all tags
1162 currently used in the buffer. You may also globally specify a hard list
1163 of tags with the variable @code{org-tag-alist}. Finally you can set
1164 the default tags for a given file with lines like
1167 #+TAGS: @@work @@home @@tennisclub
1168 #+TAGS: laptop car pc sailboat
1171 By default Org mode uses the standard minibuffer completion facilities for
1172 entering tags. However, it also implements another, quicker, tag selection
1173 method called @emph{fast tag selection}. This allows you to select and
1174 deselect tags with just a single key press. For this to work well you should
1175 assign unique letters to most of your commonly used tags. You can do this
1176 globally by configuring the variable @code{org-tag-alist} in your
1177 @file{.emacs} file. For example, you may find the need to tag many items in
1178 different files with @samp{:@@home:}. In this case you can set something
1182 (setq org-tag-alist '(("@@work" . ?w) ("@@home" . ?h) ("laptop" . ?l)))
1185 @noindent If the tag is only relevant to the file you are working on, then you
1186 can instead set the TAGS option line as:
1189 #+TAGS: @@work(w) @@home(h) @@tennisclub(t) laptop(l) pc(p)
1192 @node Tag searches, , Setting tags, Tags
1193 @section Tag searches
1195 Once a system of tags has been set up, it can be used to collect related
1196 information into special lists.
1201 Create a sparse tree with all headlines matching a tags search. With a
1202 @kbd{C-u} prefix argument, ignore headlines that are not a TODO line.
1204 Create a global list of tag matches from all agenda files.
1205 @xref{Matching tags and properties}.
1207 Create a global list of tag matches from all agenda files, but check
1208 only TODO items and force checking subitems (see variable
1209 @code{org-tags-match-list-sublevels}).
1212 These commands all prompt for a match string which allows basic Boolean logic
1213 like @samp{+boss+urgent-project1}, to find entries with tags @samp{boss} and
1214 @samp{urgent}, but not @samp{project1}, or @samp{Kathy|Sally} to find entries
1215 which are tagged, like @samp{Kathy} or @samp{Sally}. The full syntax of the
1216 search string is rich and allows also matching against TODO keywords, entry
1217 levels and properties. For a complete description with many examples, see
1218 @ref{Matching tags and properties}.
1221 @uref{http://orgmode.org/manual/Tags.html#Tags, Chapter 6 of the manual}@*
1222 @uref{http://sachachua.com/wp/2008/01/tagging-in-org-plus-bonus-code-for-timeclocks-and-tags/,
1223 Sacha Chua's article about tagging in Org-mode}}
1225 @node Properties, Dates and Times, Tags, Top
1228 Properties are key-value pairs associated with an entry. They live in a
1229 special drawer with the name @code{PROPERTIES}. Each
1230 property is specified on a single line, with the key (surrounded by colons)
1231 first, and the value after it:
1236 *** Goldberg Variations
1238 :Title: Goldberg Variations
1239 :Composer: J.S. Bach
1240 :Publisher: Deutsche Grammophon
1245 You may define the allowed values for a particular property @samp{:Xyz:}
1246 by setting a property @samp{:Xyz_ALL:}. This special property is
1247 @emph{inherited}, so if you set it in a level 1 entry, it will apply to
1248 the entire tree. When allowed values are defined, setting the
1249 corresponding property becomes easier and is less prone to typing
1250 errors. For the example with the CD collection, we can predefine
1251 publishers and the number of disks in a box like this:
1256 :NDisks_ALL: 1 2 3 4
1257 :Publisher_ALL: "Deutsche Grammophon" Philips EMI
1260 or globally using @code{org-global-properties}, or file-wide like this:
1262 #+PROPERTY: NDisks_ALL 1 2 3 4
1267 Set a property. This prompts for a property name and a value.
1269 Remove a property from the current entry.
1272 To create sparse trees and special lists with selection based on properties,
1273 the same commands are used as for tag searches (@pxref{Tag searches}). The
1274 syntax for the search string is described in @ref{Matching tags and
1281 @uref{http://orgmode.org/manual/Properties-and-Columns.html#Properties-and-Columns,
1282 Chapter 7 of the manual}@*
1283 @uref{http://orgmode.org/worg/org-tutorials/org-column-view-tutorial.php,Bastien
1284 Guerry's column view tutorial}}
1286 @node Dates and Times, Capture - Refile - Archive, Properties, Top
1287 @chapter Dates and Times
1289 To assist project planning, TODO items can be labeled with a date and/or
1290 a time. The specially formatted string carrying the date and time
1291 information is called a @emph{timestamp} in Org mode.
1294 * Timestamps:: Assigning a time to a tree entry
1295 * Creating timestamps:: Commands which insert timestamps
1296 * Deadlines and scheduling:: Planning your work
1297 * Clocking work time:: Tracking how long you spend on a task
1301 @node Timestamps, Creating timestamps, Dates and Times, Dates and Times
1304 A timestamp is a specification of a date (possibly with a time or a range of
1305 times) in a special format, either @samp{<2003-09-16 Tue>} or
1306 @samp{<2003-09-16 Tue 09:39>} or @samp{<2003-09-16 Tue 12:00-12:30>}. A
1307 timestamp can appear anywhere in the headline or body of an Org tree entry.
1308 Its presence causes entries to be shown on specific dates in the agenda
1309 (@pxref{Weekly/daily agenda}). We distinguish:
1311 @noindent @b{Plain timestamp; Event; Appointment}@*
1312 A simple timestamp just assigns a date/time to an item. This is just
1313 like writing down an appointment or event in a paper agenda.
1316 * Meet Peter at the movies
1317 <2006-11-01 Wed 19:15>
1318 * Discussion on climate change
1319 <2006-11-02 Thu 20:00-22:00>
1322 @noindent @b{Timestamp with repeater interval}@*
1323 A timestamp may contain a @emph{repeater interval}, indicating that it
1324 applies not only on the given date, but again and again after a certain
1325 interval of N days (d), weeks (w), months (m), or years (y). The
1326 following will show up in the agenda every Wednesday:
1328 * Pick up Sam at school
1329 <2007-05-16 Wed 12:30 +1w>
1332 @noindent @b{Diary-style sexp entries}@*
1333 For more complex date specifications, Org mode supports using the
1334 special sexp diary entries implemented in the Emacs calendar/diary
1335 package. For example
1337 * The nerd meeting on every 2nd Thursday of the month
1338 <%%(diary-float t 4 2)>
1341 @noindent @b{Time/Date range}@*
1342 Two timestamps connected by @samp{--} denote a range.
1344 ** Meeting in Amsterdam
1345 <2004-08-23 Mon>--<2004-08-26 Thu>
1348 @noindent @b{Inactive timestamp}@*
1349 Just like a plain timestamp, but with square brackets instead of
1350 angular ones. These timestamps are inactive in the sense that they do
1351 @emph{not} trigger an entry to show up in the agenda.
1354 * Gillian comes late for the fifth time
1359 @node Creating timestamps, Deadlines and scheduling, Timestamps, Dates and Times
1360 @section Creating timestamps
1362 For Org mode to recognize timestamps, they need to be in the specific
1363 format. All commands listed below produce timestamps in the correct
1368 Prompt for a date and insert a corresponding timestamp. When the cursor is
1369 at an existing timestamp in the buffer, the command is used to modify this
1370 timestamp instead of inserting a new one. When this command is used twice in
1371 succession, a time range is inserted. With a prefix, also add the current
1375 Like @kbd{C-c .}, but insert an inactive timestamp that will not cause
1378 @item S-@key{left}@r{/}@key{right}
1379 Change date at cursor by one day.
1381 @item S-@key{up}@r{/}@key{down}
1382 Change the item under the cursor in a timestamp. The cursor can be on a
1383 year, month, day, hour or minute. When the timestamp contains a time range
1384 like @samp{15:30-16:30}, modifying the first time will also shift the second,
1385 shifting the time block with constant length. To change the length, modify
1389 When Org mode prompts for a date/time, it will accept any string containing
1390 some date and/or time information, and intelligently interpret the string,
1391 deriving defaults for unspecified information from the current date and time.
1392 You can also select a date in the pop-up calendar. See the manual for more
1393 information on how exactly the date/time prompt works.
1395 @node Deadlines and scheduling, Clocking work time, Creating timestamps, Dates and Times
1396 @section Deadlines and scheduling
1398 A timestamp may be preceded by special keywords to facilitate planning:
1400 @noindent @b{DEADLINE}@*
1401 Meaning: the task (most likely a TODO item, though not necessarily) is supposed
1402 to be finished on that date.
1405 Insert @samp{DEADLINE} keyword along with a stamp, in the line following the
1409 On the deadline date, the task will be listed in the agenda. In
1410 addition, the agenda for @emph{today} will carry a warning about the
1411 approaching or missed deadline, starting
1412 @code{org-deadline-warning-days} before the due date, and continuing
1413 until the entry is marked DONE. An example:
1416 *** TODO write article about the Earth for the Guide
1417 The editor in charge is [[bbdb:Ford Prefect]]
1418 DEADLINE: <2004-02-29 Sun>
1422 @noindent @b{SCHEDULED}@*
1423 Meaning: you are @i{planning to start working} on that task on the given
1424 date@footnote{This is quite different from what is normally understood by
1425 @i{scheduling a meeting}, which is done in Org-mode by just inserting a time
1426 stamp without keyword.}.
1430 Insert @samp{SCHEDULED} keyword along with a stamp, in the line following the
1434 The headline will be listed under the given date@footnote{It will still
1435 be listed on that date after it has been marked DONE. If you don't like
1436 this, set the variable @code{org-agenda-skip-scheduled-if-done}.}. In
1437 addition, a reminder that the scheduled date has passed will be present
1438 in the compilation for @emph{today}, until the entry is marked DONE.
1439 I.e.@: the task will automatically be forwarded until completed.
1442 *** TODO Call Trillian for a date on New Years Eve.
1443 SCHEDULED: <2004-12-25 Sat>
1446 Some tasks need to be repeated again and again. Org mode helps to
1447 organize such tasks using a so-called repeater in a DEADLINE, SCHEDULED,
1448 or plain timestamp. In the following example
1450 ** TODO Pay the rent
1451 DEADLINE: <2005-10-01 Sat +1m>
1454 the @code{+1m} is a repeater; the intended interpretation is that the task
1455 has a deadline on <2005-10-01> and repeats itself every (one) month starting
1458 @node Clocking work time, , Deadlines and scheduling, Dates and Times
1459 @section Clocking work time
1461 Org mode allows you to clock the time you spend on specific tasks in a
1466 Start the clock on the current item (clock-in). This inserts the CLOCK
1467 keyword together with a timestamp. When called with a @kbd{C-u} prefix
1468 argument, select the task from a list of recently clocked tasks.
1471 Stop the clock (clock-out). This inserts another timestamp at the same
1472 location where the clock was last started. It also directly computes
1473 the resulting time in inserts it after the time range as @samp{=>
1476 Update the effort estimate for the current clock task.
1478 Cancel the current clock. This is useful if a clock was started by
1479 mistake, or if you ended up working on something else.
1481 Jump to the entry that contains the currently running clock. With a
1482 @kbd{C-u} prefix arg, select the target task from a list of recently clocked
1485 Insert a dynamic block containing a clock
1486 report as an Org-mode table into the current file. When the cursor is
1487 at an existing clock table, just update it.
1489 #+BEGIN: clocktable :maxlevel 2 :emphasize nil :scope file
1493 For details about how to customize this view, see @uref{http://orgmode.org/manual/Clocking-work-time.html#Clocking-work-time,the manual}.
1495 Update dynamic block at point. The cursor needs to be in the
1496 @code{#+BEGIN} line of the dynamic block.
1499 The @kbd{l} key may be used in the timeline (@pxref{Timeline}) and in
1500 the agenda (@pxref{Weekly/daily agenda}) to show which tasks have been
1501 worked on or closed during a day.
1504 @uref{http://orgmode.org/manual/Dates-and-Times.html#Dates-and-Times,
1505 Chapter 8 of the manual}@*
1506 @uref{http://members.optusnet.com.au/~charles57/GTD/org_dates/, Charles
1507 Cave's Date and Time tutorial}@*
1508 @uref{http://doc.norang.ca/org-mode.html#Clocking, Bernt Hansen's clocking workflow}}
1510 @node Capture - Refile - Archive, Agenda Views, Dates and Times, Top
1511 @chapter Capture - Refile - Archive
1513 An important part of any organization system is the ability to quickly
1514 capture new ideas and tasks, and to associate reference material with them.
1515 Org defines a capture process to create tasks. It stores files related to a
1516 task (@i{attachments}) in a special directory. Once in the system, tasks and
1517 projects need to be moved around. Moving completed project trees to an
1518 archive file keeps the system compact and fast.
1522 * Refiling notes:: Moving a tree from one place to another
1523 * Archiving:: What to do with finished projects
1526 @node Capture, Refile and copy, Capture - Refile - Archive, Capture - Refile - Archive
1529 Org's method for capturing new items is heavily inspired by John Wiegley
1530 excellent @file{remember.el} package. It lets you store quick notes with
1531 little interruption of your work flow. Org lets you define templates for new
1532 entries and associate them with different targets for storing notes.
1535 * Setting up a capture location:: Where notes will be stored
1536 * Using capture:: Commands to invoke and terminate capture
1537 * Capture templates:: Define the outline of different note types
1540 @node Setting up a capture location, Using capture, Capture, Capture
1541 @unnumberedsubsec Setting up a capture location
1543 The following customization sets a default target@footnote{Using capture
1544 templates, you can define more fine-grained capture locations, see
1545 @ref{Capture templates}.} file for notes, and defines a global
1546 key@footnote{Please select your own key, @kbd{C-c c} is only a suggestion.}
1547 for capturing new stuff.
1550 (setq org-default-notes-file (concat org-directory "/notes.org"))
1551 (define-key global-map "\C-cc" 'org-capture)
1554 @node Using capture, Capture templates, Setting up a capture location, Capture
1555 @unnumberedsubsec Using capture
1559 Start a capture process. You will be placed into a narrowed indirect buffer
1562 Once you are done entering information into the capture buffer,
1563 @kbd{C-c C-c} will return you to the window configuration before the capture
1564 process, so that you can resume your work without further distraction.
1566 Finalize by moving the entry to a refile location (@pxref{Refile and copy}).
1568 Abort the capture process and return to the previous state.
1571 @node Capture templates, , Using capture, Capture
1572 @unnumberedsubsec Capture templates
1574 You can use templates to generate different types of capture notes, and to
1575 store them in different places. For example, if you would like
1576 to store new tasks under a heading @samp{Tasks} in file @file{TODO.org}, and
1577 journal entries in a date tree in @file{journal.org} you could
1581 (setq org-capture-templates
1582 '(("t" "Todo" entry (file+headline "~/org/gtd.org" "Tasks")
1583 "* TODO %?\n %i\n %a")
1584 ("j" "Journal" entry (file+datetree "~/org/journal.org")
1585 "* %?\nEntered on %U\n %i\n %a")))
1588 @noindent In these entries, the first string is the key to reach the
1589 template, the second is a short description. Then follows the type of the
1590 entry and a definition of the target location for storing the note. Finally,
1591 the template itself, a string with %-escapes to fill in information based on
1594 When you call @kbd{M-x org-capture}, Org will prompt for a key to select the
1595 template (if you have more than one template) and then prepare the buffer like
1598 [[file:@var{link to where you were when initiating capture}]]
1602 During expansion of the template, special @kbd{%}-escapes@footnote{If you
1603 need one of these sequences literally, escape the @kbd{%} with a backslash.}
1604 allow dynamic insertion of content. Here is a small selection of the
1605 possibilities, consult the manual for more.
1607 %a @r{annotation, normally the link created with @code{org-store-link}}
1608 %i @r{initial content, the region when capture is called with C-u.}
1609 %t @r{timestamp, date only}
1610 %T @r{timestamp with date and time}
1611 %u, %U @r{like the above, but inactive timestamps}
1614 @node Refile and copy, Archiving, Capture, Capture - Refile - Archive
1615 @section Refile and copy
1617 When reviewing the captured data, you may want to refile or copy some of the
1618 entries into a different list, for example into a project. Cutting, finding
1619 the right location, and then pasting the note is cumbersome. To simplify
1620 this process, you can use the following special command:
1624 Copy the entry or region at point. This command behaves like
1625 @code{org-refile}, except that the original note will not be deleted.
1627 Refile the entry or region at point. This command offers possible locations
1628 for refiling the entry and lets you select one with completion. The item (or
1629 all items in the region) is filed below the target heading as a subitem.@*
1630 By default, all level 1 headlines in the current buffer are considered to be
1631 targets, but you can have more complex definitions across a number of files.
1632 See the variable @code{org-refile-targets} for details.
1634 Use the refile interface to jump to a heading.
1635 @item C-u C-u C-c C-w
1636 Jump to the location where @code{org-refile} last moved a tree to.
1639 @node Archiving, , Refile and copy, Capture - Refile - Archive
1642 When a project represented by a (sub)tree is finished, you may want
1643 to move the tree out of the way and to stop it from contributing to the
1644 agenda. Archiving is important to keep your working files compact and global
1645 searches like the construction of agenda views fast.
1646 The most common archiving action is to move a project tree to another file,
1651 Archive the current entry using the command specified in the variable
1652 @code{org-archive-default-command}.
1653 @item C-c C-x C-s@ @r{or short} @ C-c $
1654 Archive the subtree starting at the cursor position to the location
1655 given by @code{org-archive-location}.
1658 The default archive location is a file in the same directory as the
1659 current file, with the name derived by appending @file{_archive} to the
1660 current file name. For information and examples on how to change this,
1661 see the documentation string of the variable
1662 @code{org-archive-location}. There is also an in-buffer option for
1663 setting this variable, for example
1666 #+ARCHIVE: %s_done::
1670 @uref{http://orgmode.org/manual/Capture-_002d-Refile-_002d-Archive.html#Capture-_002d-Refile-_002d-Archive,
1671 Chapter 9 of the manual}@*
1672 @uref{http://orgmode.org/worg/org-tutorials/org-protocol-custom-handler.php,
1673 Sebastian Rose's tutorial for capturing from a web browser}}@uref{}@*
1675 @node Agenda Views, Markup, Capture - Refile - Archive, Top
1676 @chapter Agenda Views
1678 Due to the way Org works, TODO items, time-stamped items, and tagged
1679 headlines can be scattered throughout a file or even a number of files. To
1680 get an overview of open action items, or of events that are important for a
1681 particular date, this information must be collected, sorted and displayed in
1682 an organized way. There are several different views, see below.
1684 The extracted information is displayed in a special @emph{agenda buffer}.
1685 This buffer is read-only, but provides commands to visit the corresponding
1686 locations in the original Org files, and even to edit these files remotely.
1687 Remote editing from the agenda buffer means, for example, that you can
1688 change the dates of deadlines and appointments from the agenda buffer.
1689 The commands available in the Agenda buffer are listed in @ref{Agenda
1693 * Agenda files:: Files being searched for agenda information
1694 * Agenda dispatcher:: Keyboard access to agenda views
1695 * Built-in agenda views:: What is available out of the box?
1696 * Agenda commands:: Remote editing of Org trees
1697 * Custom agenda views:: Defining special searches and views
1700 @node Agenda files, Agenda dispatcher, Agenda Views, Agenda Views
1701 @section Agenda files
1703 The information to be shown is normally collected from all @emph{agenda
1704 files}, the files listed in the variable
1705 @code{org-agenda-files}.
1709 Add current file to the list of agenda files. The file is added to
1710 the front of the list. If it was already in the list, it is moved to
1711 the front. With a prefix argument, file is added/moved to the end.
1713 Remove current file from the list of agenda files.
1715 Cycle through agenda file list, visiting one file after the other.
1718 @node Agenda dispatcher, Built-in agenda views, Agenda files, Agenda Views
1719 @section The agenda dispatcher
1720 The views are created through a dispatcher, which should be bound to a
1721 global key---for example @kbd{C-c a} (@pxref{Installation}). After
1722 pressing @kbd{C-c a}, an additional letter is required to execute a
1726 The calendar-like agenda (@pxref{Weekly/daily agenda}).
1728 A list of all TODO items (@pxref{Global TODO list}).
1730 A list of headlines matching a TAGS expression (@pxref{Matching
1731 tags and properties}).
1733 The timeline view for the current buffer (@pxref{Timeline}).
1735 A list of entries selected by a boolean expression of keywords
1736 and/or regular expressions that must or must not occur in the entry.
1739 @node Built-in agenda views, Agenda commands, Agenda dispatcher, Agenda Views
1740 @section The built-in agenda views
1743 * Weekly/daily agenda:: The calendar page with current tasks
1744 * Global TODO list:: All unfinished action items
1745 * Matching tags and properties:: Structured information with fine-tuned search
1746 * Timeline:: Time-sorted view for single file
1747 * Search view:: Find entries by searching for text
1750 @node Weekly/daily agenda, Global TODO list, Built-in agenda views, Built-in agenda views
1751 @subsection The weekly/daily agenda
1753 The purpose of the weekly/daily @emph{agenda} is to act like a page of a
1754 paper agenda, showing all the tasks for the current week or day.
1758 Compile an agenda for the current week from a list of Org files. The agenda
1759 shows the entries for each day.
1762 Emacs contains the calendar and diary by Edward M. Reingold. Org-mode
1763 understands the syntax of the diary and allows you to use diary sexp entries
1764 directly in Org files:
1767 * Birthdays and similar stuff
1769 %%(org-calendar-holiday) ; special function for holiday names
1771 %%(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
1772 %%(diary-anniversary 10 2 1869) Mahatma Gandhi would be %d years old
1775 Org can interact with Emacs appointments notification facility. To add all
1776 the appointments of your agenda files, use the command
1777 @code{org-agenda-to-appt}. See the docstring for details.
1779 @node Global TODO list, Matching tags and properties, Weekly/daily agenda, Built-in agenda views
1780 @subsection The global TODO list
1782 The global TODO list contains all unfinished TODO items formatted and
1783 collected into a single place. Remote editing of TODO items lets you
1784 can change the state of a TODO entry with a single key press. The commands
1785 available in the TODO list are described in @ref{Agenda commands}.
1789 Show the global TODO list. This collects the TODO items from all
1790 agenda files (@pxref{Agenda Views}) into a single buffer.
1792 Like the above, but allows selection of a specific TODO keyword.
1795 @node Matching tags and properties, Timeline, Global TODO list, Built-in agenda views
1796 @subsection Matching tags and properties
1798 If headlines in the agenda files are marked with @emph{tags} (@pxref{Tags}),
1799 or have properties (@pxref{Properties}), you can select headlines
1800 based on this metadata and collect them into an agenda buffer. The match
1801 syntax described here also applies when creating sparse trees with @kbd{C-c /
1802 m}. The commands available in the tags list are described in @ref{Agenda
1807 Produce a list of all headlines that match a given set of tags. The
1808 command prompts for a selection criterion, which is a boolean logic
1809 expression with tags, like @samp{+work+urgent-withboss} or
1810 @samp{work|home} (@pxref{Tags}). If you often need a specific search,
1811 define a custom command for it (@pxref{Agenda dispatcher}).
1813 Like @kbd{C-c a m}, but only select headlines that are also TODO items.
1816 @subsubheading Match syntax
1818 A search string can use Boolean operators @samp{&} for AND and @samp{|} for
1819 OR. @samp{&} binds more strongly than @samp{|}. Parentheses are currently
1820 not implemented. Each element in the search is either a tag, a regular
1821 expression matching tags, or an expression like @code{PROPERTY OPERATOR
1822 VALUE} with a comparison operator, accessing a property value. Each element
1823 may be preceded by @samp{-}, to select against it, and @samp{+} is syntactic
1824 sugar for positive selection. The AND operator @samp{&} is optional when
1825 @samp{+} or @samp{-} is present. Here are some examples, using only tags.
1829 Select headlines tagged @samp{:work:}, but discard those also tagged
1832 Selects lines tagged @samp{:work:} or @samp{:laptop:}.
1833 @item work|laptop+night
1834 Like before, but require the @samp{:laptop:} lines to be tagged also
1838 You may also test for properties at the same
1839 time as matching tags, see the manual for more information.
1841 @node Timeline, Search view, Matching tags and properties, Built-in agenda views
1842 @subsection Timeline for a single file
1844 The timeline summarizes all time-stamped items from a single Org mode
1845 file in a @emph{time-sorted view}. The main purpose of this command is
1846 to give an overview over events in a project.
1850 Show a time-sorted view of the Org file, with all time-stamped items.
1851 When called with a @kbd{C-u} prefix, all unfinished TODO entries
1852 (scheduled or not) are also listed under the current date.
1855 @node Search view, , Timeline, Built-in agenda views
1856 @subsection Search view
1858 This agenda view is a general text search facility for Org mode entries.
1859 It is particularly useful to find notes.
1863 This is a special search that lets you select entries by matching a substring
1864 or specific words using a boolean logic.
1866 For example, the search string @samp{computer equipment} will find entries
1867 that contain @samp{computer equipment} as a substring.
1868 Search view can also search for specific keywords in the entry, using Boolean
1869 logic. The search string @samp{+computer +wifi -ethernet -@{8\.11[bg]@}}
1870 will search for note entries that contain the keywords @code{computer}
1871 and @code{wifi}, but not the keyword @code{ethernet}, and which are also
1872 not matched by the regular expression @code{8\.11[bg]}, meaning to
1873 exclude both 8.11b and 8.11g.
1875 Note that in addition to the agenda files, this command will also search
1876 the files listed in @code{org-agenda-text-search-extra-files}.
1878 @node Agenda commands, Custom agenda views, Built-in agenda views, Agenda Views
1879 @section Commands in the agenda buffer
1881 Entries in the agenda buffer are linked back to the Org file or diary
1882 file where they originate. Commands are provided to show and jump to the
1883 original entry location, and to edit the Org files ``remotely'' from
1884 the agenda buffer. This is just a selection of the many commands, explore
1885 the @code{Agenda} menu and the manual for a complete list.
1888 @tsubheading{Motion}
1890 Next line (same as @key{up} and @kbd{C-p}).
1892 Previous line (same as @key{down} and @kbd{C-n}).
1893 @tsubheading{View/Go to Org file}
1896 Display the original location of the item in another window.
1897 With prefix arg, make sure that the entire entry is made visible in the
1898 outline, not only the heading.
1901 Go to the original location of the item in another window. Under Emacs
1902 22, @kbd{mouse-1} will also work for this.
1905 Go to the original location of the item and delete other windows.
1908 @tsubheading{Change display}
1910 Delete other windows.
1913 Switch to day/week view.
1916 Go forward/backward in time to display the following
1917 @code{org-agenda-current-span} days. For example, if the display covers a
1918 week, switch to the following/previous week.
1924 Prompt for a date and go there.
1926 @item v l @ @r{or short} @ l
1927 Toggle Logbook mode. In Logbook mode, entries that were marked DONE while
1928 logging was on (variable @code{org-log-done}) are shown in the agenda, as are
1929 entries that have been clocked on that day. When called with a @kbd{C-u}
1930 prefix, show all possible logbook entries, including state changes.
1933 Recreate the agenda buffer, to reflect the changes.
1935 Save all Org buffers in the current Emacs session, and also the locations of
1938 @tsubheading{Secondary filtering and query editing}
1941 Filter the current agenda view with respect to a tag. You are prompted for a
1942 letter to select a tag. Press @samp{-} first to select against the tag.
1945 Narrow the current agenda filter by an additional condition.
1947 @tsubheading{Remote editing (see the manual for many more commands)}
1953 Change the TODO state of the item, in the agenda and in the
1957 Delete the current agenda item along with the entire subtree belonging
1958 to it in the original Org file.
1961 Refile the entry at point.
1963 @item C-c C-x C-a @ @r{or short} @ a
1964 Archive the subtree corresponding to the entry at point using the default
1965 archiving command set in @code{org-archive-default-command}.
1967 @item C-c C-x C-s @ @r{or short} @ $
1968 Archive the subtree corresponding to the current headline.
1971 Schedule this item, with prefix arg remove the scheduling timestamp
1974 Set a deadline for this item, with prefix arg remove the deadline.
1976 @item S-@key{right} @r{and} S-@key{left}
1977 Change the timestamp associated with the current line by one day.
1980 Start the clock on the current item.
1983 Stop/cancel the previously started clock.
1986 Jump to the running clock in another window.
1989 @node Custom agenda views, , Agenda commands, Agenda Views
1990 @section Custom agenda views
1992 The main application of custom searches is the definition of keyboard
1993 shortcuts for frequently used searches, either creating an agenda
1994 buffer, or a sparse tree (the latter covering of course only the current
1996 Custom commands are configured in the variable
1997 @code{org-agenda-custom-commands}. You can customize this variable, for
1998 example by pressing @kbd{C-c a C}. You can also directly set it with
1999 Emacs Lisp in @file{.emacs}. The following example contains all valid
2004 (setq org-agenda-custom-commands
2005 '(("w" todo "WAITING")
2006 ("u" tags "+boss-urgent")
2007 ("v" tags-todo "+boss-urgent")))
2012 The initial string in each entry defines the keys you have to press after the
2013 dispatcher command @kbd{C-c a} in order to access the command. Usually this
2014 will be just a single character. The second parameter is the search type,
2015 followed by the string or regular expression to be used for the matching.
2016 The example above will therefore define:
2020 as a global search for TODO entries with @samp{WAITING} as the TODO
2023 as a global tags search for headlines marked @samp{:boss:} but not
2026 as the same search as @kbd{C-c a u}, but limiting the search to
2027 headlines that are also TODO items
2031 @uref{http://orgmode.org/manual/Agenda-Views.html#Agenda-Views, Chapter 10 of
2033 @uref{http://orgmode.org/worg/org-tutorials/org-custom-agenda-commands.php,
2034 Mat Lundin's tutorial about custom agenda commands}@*
2035 @uref{http://www.newartisans.com/2007/08/using-org-mode-as-a-day-planner.html,
2036 John Wiegley's setup}}
2038 @node Markup, Exporting, Agenda Views, Top
2039 @chapter Markup for rich export
2041 When exporting Org-mode documents, the exporter tries to reflect the
2042 structure of the document as accurately as possible in the backend. Since
2043 export targets like HTML, @LaTeX{}, or DocBook allow much richer formatting,
2044 Org mode has rules on how to prepare text for rich export. This section
2045 summarizes the markup rules used in an Org-mode buffer.
2048 * Structural markup elements:: The basic structure as seen by the exporter
2049 * Images and tables:: Tables and Images will be included
2050 * Literal examples:: Source code examples with special formatting
2051 * Include files:: Include additional files into a document
2052 * Embedded @LaTeX{}:: @LaTeX{} can be freely used inside Org documents
2055 @node Structural markup elements, Images and tables, Markup, Markup
2056 @section Structural markup elements
2059 * Document title:: Where the title is taken from
2060 * Headings and sections:: The document structure as seen by the exporter
2061 * Table of contents:: The if and where of the table of contents
2062 * Paragraphs:: Paragraphs
2063 * Emphasis and monospace:: Bold, italic, etc.
2064 * Comment lines:: What will *not* be exported
2067 @node Document title, Headings and sections, Structural markup elements, Structural markup elements
2068 @subheading Document title
2071 The title of the exported document is taken from the special line
2074 #+TITLE: This is the title of the document
2077 @node Headings and sections, Table of contents, Document title, Structural markup elements
2078 @subheading Headings and sections
2080 The outline structure of the document as described in @ref{Document
2081 Structure}, forms the basis for defining sections of the exported document.
2082 However, since the outline structure is also used for (for example) lists of
2083 tasks, only the first three outline levels will be used as headings. Deeper
2084 levels will become itemized lists. You can change the location of this
2085 switch globally by setting the variable @code{org-export-headline-levels}, or on a
2086 per-file basis with a line
2092 @node Table of contents, Paragraphs, Headings and sections, Structural markup elements
2093 @subheading Table of contents
2095 The table of contents is normally inserted directly before the first headline
2099 #+OPTIONS: toc:2 (only to two levels in TOC)
2100 #+OPTIONS: toc:nil (no TOC at all)
2103 @node Paragraphs, Emphasis and monospace, Table of contents, Structural markup elements
2104 @subheading Paragraphs, line breaks, and quoting
2106 Paragraphs are separated by at least one empty line. If you need to enforce
2107 a line break within a paragraph, use @samp{\\} at the end of a line.
2109 To keep the line breaks in a region, but otherwise use normal formatting, you
2110 can use this construct, which can also be used to format poetry.
2114 Great clouds overhead
2115 Tiny black birds rise and fall
2122 When quoting a passage from another document, it is customary to format this
2123 as a paragraph that is indented on both the left and the right margin. You
2124 can include quotations in Org-mode documents like this:
2128 Everything should be made as simple as possible,
2129 but not any simpler -- Albert Einstein
2133 If you would like to center some text, do it like this:
2136 Everything should be made as simple as possible, \\
2141 @node Emphasis and monospace, Comment lines, Paragraphs, Structural markup elements
2142 @subheading Emphasis and monospace
2144 You can make words @b{*bold*}, @i{/italic/}, _underlined_, @code{=code=}
2145 and @code{~verbatim~}, and, if you must, @samp{+strike-through+}. Text
2146 in the code and verbatim string is not processed for Org-mode specific
2147 syntax, it is exported verbatim. To insert a horizontal rules, use a line
2148 consisting of only dashes, and at least 5 of them.
2150 @node Comment lines, , Emphasis and monospace, Structural markup elements
2151 @subheading Comment lines
2153 Lines starting with zero or more whitespace characters followed by @samp{#}
2154 are treated as comments and will never be exported. Also entire subtrees
2155 starting with the word @samp{COMMENT} will never be exported. Finally,
2156 regions surrounded by @samp{#+BEGIN_COMMENT} ... @samp{#+END_COMMENT} will
2161 Toggle the COMMENT keyword at the beginning of an entry.
2164 @node Images and tables, Literal examples, Structural markup elements, Markup
2165 @section Images and Tables
2167 For Org mode tables, the lines before the first horizontal separator line
2168 will become table header lines. You can use the following lines somewhere
2169 before the table to assign a caption and a label for cross references, and in
2170 the text you can refer to the object with @code{\ref@{tab:basic-data@}}:
2173 #+CAPTION: This is the caption for the next table (or link)
2174 #+LABEL: tbl:basic-data
2179 Some backends (HTML, @LaTeX{}, and DocBook) allow you to directly include
2180 images into the exported document. Org does this, if a link to an image
2181 files does not have a description part, for example @code{[[./img/a.jpg]]}.
2182 If you wish to define a caption for the image and maybe a label for internal
2183 cross references, you sure that the link is on a line by itself precede it
2187 #+CAPTION: This is the caption for the next figure link (or table)
2188 #+LABEL: fig:SED-HR4049
2192 You may also define additional attributes for the figure. As this is
2193 backend-specific, see the sections about the individual backends for more
2197 @node Literal examples, Include files, Images and tables, Markup
2198 @section Literal examples
2200 You can include literal examples that should not be subjected to
2201 markup. Such examples will be typeset in monospace, so this is well suited
2202 for source code and similar examples.
2206 Some example from a text file.
2210 For simplicity when using small examples, you can also start the example
2211 lines with a colon followed by a space. There may also be additional
2212 whitespace before the colon:
2216 : Some example from a text file.
2219 For source code from a programming language, or any other text
2220 that can be marked up by font-lock in Emacs, you can ask for it to
2221 look like the fontified Emacs buffer
2224 #+BEGIN_SRC emacs-lisp
2225 (defun org-xor (a b)
2231 To edit the example in a special buffer supporting this language, use
2232 @kbd{C-c '} to both enter and leave the editing buffer.
2234 @node Include files, Embedded @LaTeX{}, Literal examples, Markup
2235 @section Include files
2237 During export, you can include the content of another file. For example, to
2238 include your @file{.emacs} file, you could use:
2241 #+INCLUDE: "~/.emacs" src emacs-lisp
2244 The optional second and third parameter are the markup (e.g.@: @samp{quote},
2245 @samp{example}, or @samp{src}), and, if the markup is @samp{src}, the
2246 language for formatting the contents. The markup is optional, if it is not
2247 given, the text will be assumed to be in Org mode format and will be
2248 processed normally. @kbd{C-c '} will visit the included file.
2250 @node Embedded @LaTeX{}, , Include files, Markup
2251 @section Embedded @LaTeX{}
2253 For scientific notes which need to be able to contain mathematical symbols
2254 and the occasional formula, Org-mode supports embedding @LaTeX{} code into
2255 its files. You can directly use TeX-like macros for special symbols, enter
2256 formulas and entire @LaTeX{} environments.
2259 Angles are written as Greek letters \alpha, \beta and \gamma. The mass if
2260 the sun is M_sun = 1.989 x 10^30 kg. The radius of the sun is R_@{sun@} =
2261 6.96 x 10^8 m. If $a^2=b$ and $b=2$, then the solution must be either
2262 $a=+\sqrt@{2@}$ or $a=-\sqrt@{2@}$.
2269 @uref{http://orgmode.org/manual/LaTeX-fragments.html#LaTeX-fragments,special
2270 setup}, @LaTeX{} snippets will be included as images when exporting to HTML.
2273 @uref{http://orgmode.org/manual/Markup.html#Markup, Chapter 11 of the manual}}
2275 @node Exporting, Publishing, Markup, Top
2278 Org-mode documents can be exported into a variety of other formats: ASCII
2279 export for inclusion into emails, HTML to publish on the web, @LaTeX{}/PDF
2280 for beautiful printed documents and DocBook to enter the world of many other
2281 formats using DocBook tools. There is also export to iCalendar format so
2282 that planning information can be incorporated into desktop calendars.
2285 * Export options:: Per-file export settings
2286 * The export dispatcher:: How to access exporter commands
2287 * ASCII/Latin-1/UTF-8 export:: Exporting to flat files with encoding
2288 * HTML export:: Exporting to HTML
2289 * @LaTeX{} and PDF export:: Exporting to @LaTeX{}, and processing to PDF
2290 * DocBook export:: Exporting to DocBook
2291 * iCalendar export::
2294 @node Export options, The export dispatcher, Exporting, Exporting
2295 @section Export options
2297 The exporter recognizes special lines in the buffer which provide
2298 additional information. These lines may be put anywhere in the file.
2299 The whole set of lines can be inserted into the buffer with @kbd{C-c
2304 Insert template with export options, see example below.
2308 #+TITLE: the title to be shown (default is the buffer name)
2309 #+AUTHOR: the author (default taken from @code{user-full-name})
2310 #+DATE: a date, fixed, of a format string for @code{format-time-string}
2311 #+EMAIL: his/her email address (default from @code{user-mail-address})
2312 #+DESCRIPTION: the page description, e.g.@: for the XHTML meta tag
2313 #+KEYWORDS: the page keywords, e.g.@: for the XHTML meta tag
2314 #+LANGUAGE: language for HTML, e.g.@: @samp{en} (@code{org-export-default-language})
2315 #+TEXT: Some descriptive text to be inserted at the beginning.
2316 #+TEXT: Several lines may be given.
2317 #+OPTIONS: H:2 num:t toc:t \n:nil @@:t ::t |:t ^:t f:t TeX:t ...
2318 #+LINK_UP: the ``up'' link of an exported page
2319 #+LINK_HOME: the ``home'' link of an exported page
2320 #+LATEX_HEADER: extra line(s) for the @LaTeX{} header, like \usepackage@{xyz@}
2323 @node The export dispatcher, ASCII/Latin-1/UTF-8 export, Export options, Exporting
2324 @section The export dispatcher
2326 All export commands can be reached using the export dispatcher, which is a
2327 prefix key that prompts for an additional key specifying the command.
2328 Normally the entire file is exported, but if there is an active region that
2329 contains one outline tree, the first heading is used as document title and
2330 the subtrees are exported.
2334 Dispatcher for export and publishing commands.
2337 @node ASCII/Latin-1/UTF-8 export, HTML export, The export dispatcher, Exporting
2338 @section ASCII/Latin-1/UTF-8 export
2340 ASCII export produces a simple and very readable version of an Org-mode
2341 file, containing only plain ASCII. Latin-1 and UTF-8 export augment the file
2342 with special characters and symbols available in these encodings.
2346 Export as ASCII file.
2347 @item C-c C-e n @ @ @r{and} @ @ C-c C-e N
2348 Like the above commands, but use Latin-1 encoding.
2349 @item C-c C-e u @ @ @r{and} @ @ C-c C-e U
2350 Like the above commands, but use UTF-8 encoding.
2353 @node HTML export, @LaTeX{} and PDF export, ASCII/Latin-1/UTF-8 export, Exporting
2354 @section HTML export
2358 Export as HTML file @file{myfile.html}.
2360 Export as HTML file and immediately open it with a browser.
2363 To insert HTML that should be copied verbatim to
2364 the exported file use either
2367 #+HTML: Literal HTML code for export
2372 All lines between these markers are exported literally
2376 @node @LaTeX{} and PDF export, DocBook export, HTML export, Exporting
2377 @section @LaTeX{} and PDF export
2381 Export as @LaTeX{} file @file{myfile.tex}.
2383 Export as @LaTeX{} and then process to PDF.
2385 Export as @LaTeX{} and then process to PDF, then open the resulting PDF file.
2388 By default, the @LaTeX{} output uses the class @code{article}. You can
2389 change this by adding an option like @code{#+LaTeX_CLASS: myclass} in your
2390 file. The class must be listed in @code{org-latex-classes}.
2392 Embedded @LaTeX{} as described in @ref{Embedded @LaTeX{}}, will be correctly
2393 inserted into the @LaTeX{} file. Similarly to the HTML exporter, you can use
2394 @code{#+LaTeX:} and @code{#+BEGIN_LaTeX ... #+END_LaTeX} construct to add
2395 verbatim @LaTeX{} code.
2397 @node DocBook export, iCalendar export, @LaTeX{} and PDF export, Exporting
2398 @section DocBook export
2402 Export as DocBook file.
2405 Similarly to the HTML exporter, you can use @code{#+DOCBOOK:} and
2406 @code{#+BEGIN_DOCBOOK ... #+END_DOCBOOK} construct to add verbatim @LaTeX{}
2409 @node iCalendar export, , DocBook export, Exporting
2410 @section iCalendar export
2414 Create iCalendar entries for the current file in a @file{.ics} file.
2416 Create a single large iCalendar file from all files in
2417 @code{org-agenda-files} and write it to the file given by
2418 @code{org-combined-agenda-icalendar-file}.
2422 @uref{http://orgmode.org/manual/Exporting.html#Exporting, Chapter 12 of the manual}@*
2423 @uref{http://orgmode.org/worg/org-tutorials/images-and-xhtml-export.php,
2424 Sebastian Rose's image handling tutorial}@*
2425 @uref{http://orgmode.org/worg/org-tutorials/org-latex-export.php, Thomas
2426 Dye's LaTeX export tutorial}
2427 @uref{http://orgmode.org/worg/org-tutorials/org-beamer/tutorial.php, Eric
2428 Fraga's BEAMER presentation tutorial}}
2430 @node Publishing, Working With Source Code, Exporting, Top
2433 Org includes a publishing management system that allows you to configure
2434 automatic HTML conversion of @emph{projects} composed of interlinked org
2435 files. You can also configure Org to automatically upload your exported HTML
2436 pages and related attachments, such as images and source code files, to a web
2437 server. For detailed instructions about setup, see the manual.
2442 (setq org-publish-project-alist
2444 :base-directory "~/org/"
2445 :publishing-directory "~/public_html"
2446 :section-numbers nil
2447 :table-of-contents nil
2448 :style "<link rel=\"stylesheet\"
2449 href=\"../other/mystyle.css\"
2450 type=\"text/css\"/>")))
2455 Prompt for a specific project and publish all files that belong to it.
2457 Publish the project containing the current file.
2459 Publish only the current file.
2461 Publish every project.
2464 Org uses timestamps to track when a file has changed. The above functions
2465 normally only publish changed files. You can override this and force
2466 publishing of all files by giving a prefix argument to any of the commands
2470 @uref{http://orgmode.org/manual/Publishing.html#Publishing, Chapter 13 of the
2472 @uref{http://orgmode.org/worg/org-tutorials/org-publish-html-tutorial.php,
2473 Sebastian Rose's publishing tutorial}@*
2474 @uref{http://orgmode.org/worg/org-tutorials/org-jekyll.php, Ian Barton's
2475 Jekyll/blogging setup}}
2477 @node Working With Source Code, Miscellaneous, Publishing, Top
2478 @chapter Working with source code
2479 Org-mode provides a number of features for working with source code,
2480 including editing of code blocks in their native major-mode, evaluation of
2481 code blocks, tangling of code blocks, and exporting code blocks and their
2482 results in several formats.
2484 @subheading Structure of Code Blocks
2485 The structure of code blocks is as follows:
2489 #+BEGIN_SRC <language> <switches> <header arguments>
2494 Where @code{<name>} is a string used to name the code block,
2495 @code{<language>} specifies the language of the code block
2496 (e.g.@: @code{emacs-lisp}, @code{shell}, @code{R}, @code{python}, etc...),
2497 @code{<switches>} can be used to control export of the code block,
2498 @code{<header arguments>} can be used to control many aspects of code block
2499 behavior as demonstrated below, and @code{<body>} contains the actual source
2502 @subheading Editing source code
2503 Use @kbd{C-c '} to edit the current code block. This brings up a language
2504 major-mode edit buffer containing the body of the code block. Saving this
2505 buffer will write the new contents back to the Org buffer. Use @kbd{C-c '}
2506 again to exit the edit buffer.
2508 @subheading Evaluating code blocks
2509 Use @kbd{C-c C-c} to evaluate the current code block and insert its results
2510 in the Org-mode buffer. By default, evaluation is only turned on for
2511 @code{emacs-lisp} code blocks, however support exists for evaluating blocks
2512 in many languages. For a complete list of supported languages see the
2513 manual. The following shows a code block and its results.
2516 #+BEGIN_SRC emacs-lisp
2524 @subheading Extracting source code
2525 Use @kbd{C-c C-v t} to create pure source code files by extracting code from
2526 source blocks in the current buffer. This is referred to as ``tangling''---a
2527 term adopted from the literate programming community. During ``tangling'' of
2528 code blocks their bodies are expanded using @code{org-babel-expand-src-block}
2529 which can expand both variable and ``noweb'' style references. In order to
2530 tangle a code block it must have a @code{:tangle} header argument, see the
2533 @subheading Library of Babel
2534 Use @kbd{C-c C-v l} to load the code blocks from an Org-mode files into the
2535 ``Library of Babel'', these blocks can then be evaluated from any Org-mode
2536 buffer. A collection of generally useful code blocks is distributed with
2537 Org-mode in @code{contrib/library-of-babel.org}.
2539 @subheading Header Arguments
2540 Many aspects of the evaluation and export of code blocks are controlled
2541 through header arguments. These can be specified globally, at the file
2542 level, at the outline subtree level, and at the individual code block level.
2543 The following describes some of the header arguments.
2546 The @code{:var} header argument is used to pass arguments to code blocks.
2547 The values passed to arguments can be literal values, values from org-mode
2548 tables and literal example blocks, or the results of other named code blocks.
2550 The @code{:results} header argument controls the @emph{collection},
2551 @emph{type}, and @emph{handling} of code block results. Values of
2552 @code{output} or @code{value} (the default) specify how results are collected
2553 from a code block's evaluation. Values of @code{vector}, @code{scalar}
2554 @code{file} @code{raw} @code{html} @code{latex} and @code{code} specify the
2555 type of the results of the code block which dictates how they will be
2556 incorporated into the Org-mode buffer. Values of @code{silent},
2557 @code{replace}, @code{prepend}, and @code{append} specify handling of code
2558 block results, specifically if and how the results should be inserted into
2559 the Org-mode buffer.
2561 A header argument of @code{:session} will cause the code block to be
2562 evaluated in a persistent interactive inferior process in Emacs. This allows
2563 for persisting state between code block evaluations, and for manual
2564 inspection of the results of evaluation.
2566 Any combination of the @emph{code} or the @emph{results} of a block can be
2567 retained on export, this is specified by setting the @code{:results} header
2568 argument to @code{code} @code{results} @code{none} or @code{both}.
2570 A header argument of @code{:tangle yes} will cause a code block's contents to
2571 be tangled to a file named after the filename of the Org-mode buffer. An
2572 alternate file name can be specified with @code{:tangle filename}.
2574 A header argument of @code{:cache yes} will cause associate a hash of the
2575 expanded code block with the results, ensuring that code blocks are only
2576 re-run when their inputs have changed.
2578 A header argument of @code{:noweb yes} will expand ``noweb'' style references
2579 on evaluation and tangling.
2581 Code blocks which output results to files (e.g.@: graphs, diagrams and figures)
2582 can accept a @code{:file filename} header argument in which case the results
2583 are saved to the named file, and a link to the file is inserted into the
2588 @uref{http://orgmode.org/manual/Literal-examples.html#Literal-examples,
2589 Chapter 11.3 of the manual}@*
2590 @uref{http://orgmode.org/worg/org-contrib/babel/index.php,
2591 The Babel site on Worg}}
2593 @node Miscellaneous, GNU Free Documentation License, Working With Source Code, Top
2594 @chapter Miscellaneous
2597 * Completion:: M-TAB knows what you need
2598 * Clean view:: Getting rid of leading stars in the outline
2599 * MobileOrg:: Org-mode on the iPhone
2602 @node Completion, Clean view, Miscellaneous, Miscellaneous
2605 Org supports in-buffer completion with @kbd{M-@key{TAB}}. This type of
2606 completion does not make use of the minibuffer. You simply type a few
2607 letters into the buffer and use the key to complete text right there. For
2608 example, this command will complete @TeX{} symbols after @samp{\}, TODO
2609 keywords at the beginning of a headline, and tags after @samp{:} in a
2612 @node Clean view, MobileOrg, Completion, Miscellaneous
2613 @section A cleaner outline view
2615 Some people find it noisy and distracting that the Org headlines start with a
2616 potentially large number of stars, and that text below the headlines is not
2617 indented. While this is no problem when writing a @emph{book-like} document
2618 where the outline headings are really section headings, in a more
2619 @emph{list-oriented} outline, indented structure is a lot cleaner:
2623 * Top level headline | * Top level headline
2624 ** Second level | * Second level
2625 *** 3rd level | * 3rd level
2626 some text | some text
2627 *** 3rd level | * 3rd level
2628 more text | more text
2629 * Another top level headline | * Another top level headline
2634 If you are using at least Emacs 23.1.50.3 and version 6.29 of Org, this kind
2635 of view can be achieved dynamically at display time using
2636 @code{org-indent-mode}, which will prepend intangible space to each line.
2637 You can turn on @code{org-indent-mode} for all files by customizing the
2638 variable @code{org-startup-indented}, or you can turn it on for individual
2645 If you want a similar effect in earlier version of Emacs and/or Org, or if
2646 you want the indentation to be hard space characters so that the plain text
2647 file looks as similar as possible to the Emacs display, Org supports you by
2648 helping to indent (with @key{TAB}) text below each headline, by hiding
2649 leading stars, and by only using levels 1, 3, etc to get two characters
2650 indentation for each level. To get this support in a file, use
2653 #+STARTUP: hidestars odd
2656 @node MobileOrg, , Clean view, Miscellaneous
2659 @i{MobileOrg} is the name of the mobile companion app for Org mode, currently
2660 available for iOS and for Android. @i{MobileOrg} offers offline viewing and
2661 capture support for an Org mode system rooted on a ``real'' computer. It
2662 does also allow you to record changes to existing entries.
2664 The @uref{http://mobileorg.ncogni.to/, iOS implementation} for the
2665 @i{iPhone/iPod Touch/iPad} series of devices, was developed by Richard
2666 Moreland. Android users should check out
2667 @uref{http://wiki.github.com/matburt/mobileorg-android/, MobileOrg Android}
2668 by Matt Jones. The two implementations are not identical but offer similar
2672 @uref{http://orgmode.org/manual/Miscellaneous.html#Miscellaneous, Chapter 15
2674 @uref{http://orgmode.org/manual/MobileOrg.html#MobileOrg, Appendix B of the
2676 @uref{http://orgmode.org/orgcard.pdf,Key reference card}}
2679 @node GNU Free Documentation License, , Miscellaneous, Top
2680 @appendix GNU Free Documentation License
2681 @include doclicense.texi
2691 @c LocalWords: webdavhost pre