From c38d101fff2f362d66db29153c6aa80ba9acab75 Mon Sep 17 00:00:00 2001 From: Carsten Dominik Date: Wed, 28 Apr 2010 08:53:17 +0200 Subject: [PATCH] New compact Org-mode guide --- Makefile | 23 +- ORGWEBPAGE/index.org | 6 +- UTILITIES/guidesplit.pl | 62 ++ doc/orgguide.texi | 2595 +++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 2681 insertions(+), 5 deletions(-) create mode 100755 UTILITIES/guidesplit.pl create mode 100644 doc/orgguide.texi diff --git a/Makefile b/Makefile index a7e14c05f..624e9631a 100644 --- a/Makefile +++ b/Makefile @@ -45,6 +45,7 @@ MAKEINFO = makeinfo # How to create the HTML file TEXI2HTML = makeinfo --html --number-sections +TEXI2HTMLNOPSLIT = makeinfo --html --no-split --number-sections # How to copy the lisp files and elc files to their distination. CP = cp -p @@ -116,7 +117,8 @@ LISPFILES0 = $(LISPF:%=lisp/%) LISPFILES = $(LISPFILES0) lisp/org-install.el ELCFILES0 = $(LISPFILES0:.el=.elc) ELCFILES = $(LISPFILES:.el=.elc) -DOCFILES = doc/org.texi doc/org.pdf doc/org doc/dir doc/.nosearch +DOCFILES = doc/org.texi doc/org.pdf doc/org doc/dir doc/.nosearch \ + doc/orgguide.texi doc/orgguide.pdf CARDFILES = doc/orgcard.tex doc/orgcard.pdf doc/orgcard_letter.pdf TEXIFILES = doc/org.texi INFOFILES = doc/org @@ -145,11 +147,14 @@ compile: $(ELCFILES0) install: install-lisp -doc: doc/org.html doc/org.pdf doc/orgcard.pdf doc/orgcard_letter.pdf +doc: doc/org.html doc/org.pdf doc/orgcard.pdf doc/orgcard_letter.pdf doc/orgguide.pdf p: ${MAKE} pdf && open doc/org.pdf +g: + ${MAKE} pdf && open doc/orgguide.pdf + install-lisp: $(LISPFILES) $(ELCFILES) if [ ! -d $(lispdir) ]; then $(MKDIR) $(lispdir); else true; fi ; $(CP) $(LISPFILES) $(lispdir) @@ -186,6 +191,9 @@ doc/org: doc/org.texi doc/org.pdf: doc/org.texi (cd doc; $(TEXI2PDF) org.texi) +doc/orgguide.pdf: doc/orgguide.texi + (cd doc; $(TEXI2PDF) orgguide.texi) + doc/org.html: doc/org.texi (cd doc; $(TEXI2HTML) --no-split -o org.html org.texi) UTILITIES/manfull.pl doc/org.html @@ -213,9 +221,15 @@ html_manual: doc/org.texi $(TEXI2HTML) -o doc/manual doc/org.texi UTILITIES/mansplit.pl doc/manual/*.html +html_guide: doc/orgguide.texi + rm -rf doc/guide + mkdir doc/guide + $(TEXI2HTML) -o doc/guide doc/orgguide.texi + UTILITIES/guidesplit.pl doc/guide/*.html + info: doc/org -pdf: doc/org.pdf +pdf: doc/org.pdf doc/orgguide.pdf card: doc/orgcard.pdf doc/orgcard_letter.pdf @@ -246,10 +260,12 @@ release: ${MAKE} doc UTILITIES/gplmanual.pl ${MAKE} html_manual + ${MAKE} html_guide rm -rf RELEASEDIR $(MKDIR) RELEASEDIR cp org-$(TAG).zip org-$(TAG).tar.gz RELEASEDIR cp doc/org.pdf doc/orgcard.pdf doc/org.texi doc/org.html RELEASEDIR + cp doc/orgguide.pdf RELEASEDIR cp RELEASEDIR/org-$(TAG).zip RELEASEDIR/org.zip cp RELEASEDIR/org-$(TAG).tar.gz RELEASEDIR/org.tar.gz @@ -258,6 +274,7 @@ upload_release: upload_manual: rsync -avuz --delete doc/manual/ cdominik@orgmode.org:orgmode.org/manual/ + rsync -avuz --delete doc/guide/ cdominik@orgmode.org:orgmode.org/guide/ relup0: ${MAKE} release diff --git a/ORGWEBPAGE/index.org b/ORGWEBPAGE/index.org index f8cc64160..3b56db51d 100644 --- a/ORGWEBPAGE/index.org +++ b/ORGWEBPAGE/index.org @@ -168,11 +168,13 @@ and corresponding to the latest git version. * Documentation ** The Org manual - - Read the [[file:manual/index.html][documentation online]]. + - Read the [[file:manual/index.html][manual online]]. - You can also have the entire manual in a [[file:org.html][single monolithic file]]. - - Download the documentation as a [[file:org.pdf][PDF document]]. + - Download the manual as a [[file:org.pdf][PDF document]]. - A [[http://hpcgi1.nifty.com/spen/index.cgi?OrgMode%2fManual][Japanese translation]] of the manual (version 4.60), by Takeshi Okano. + - The Org-mode Guide is a compact version of the manual, with all + basic information. Read the [[file:guide/index.html][guide online]] or as a [[file:orgguide.pdf][PDF document]] ** Reference card - Download the [[file:orgcard.pdf][Refcard]] for org-mode diff --git a/UTILITIES/guidesplit.pl b/UTILITIES/guidesplit.pl new file mode 100755 index 000000000..47152f157 --- /dev/null +++ b/UTILITIES/guidesplit.pl @@ -0,0 +1,62 @@ +#!/usr/bin/perl +# Work on the files that are created by makeinfo for html output +# split into many small files. + +# This will walk though the files listed on the command line, install +# Sebastian Rose's key reader and add a small top-level-only table +# of contents that will be placed into a special region and visible +# in all subfiles. The small contents is a constant and has to be updated +# by hand, currently. + +$contents = < +

Table of Contents

+
+ +
+ + +EOF + +$script = <<'EOF'; + + + +EOF + +while ($page = shift) { +system "mv $page $page.orig"; +open IN,"<$page.orig" or die "Cannot read from $page.orig\n"; +undef $/; +$all = ; +close IN; + +$all =~ s//$&\n$script/; +$all =~ s/^/\n$contents/m; + +open OUT,">$page" or die "Cannot write to $page\n"; +print OUT $all; +close OUT; +system "rm $page.orig"; +} diff --git a/doc/orgguide.texi b/doc/orgguide.texi new file mode 100644 index 000000000..e3e45bc21 --- /dev/null +++ b/doc/orgguide.texi @@ -0,0 +1,2595 @@ +\input texinfo +@c %**start of header +@setfilename ../../info/orgguide +@settitle The compact Org-mode Guide + +@set VERSION 0.92 +@set DATE April 2010 + +@c Version and Contact Info +@set MAINTAINERSITE @uref{http://orgmode.org,maintainers webpage} +@set AUTHOR Carsten Dominik +@set MAINTAINER Carsten Dominik +@set MAINTAINEREMAIL @email{carsten at orgmode dot org} +@set MAINTAINERCONTACT @uref{mailto:carsten at orgmode dot org,contact the maintainer} +@c %**end of header +@finalout + +@c Macro definitions +@iftex +@c @hyphenation{time-stamp time-stamps time-stamp-ing time-stamp-ed} +@end iftex +@macro Ie {} +I.e., +@end macro +@macro ie {} +i.e., +@end macro +@macro Eg {} +E.g., +@end macro +@macro eg {} +e.g., +@end macro + +@c Subheadings inside a table. +@macro tsubheading{text} +@ifinfo +@subsubheading \text\ +@end ifinfo +@ifnotinfo +@item @b{\text\} +@end ifnotinfo +@end macro + +@macro seealso{text} +@noindent @b{Further reading}@*@noindent \text\ +@end macro +@copying + +Copyright @copyright{} 2010 Free Software Foundation + +@quotation +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover texts being ``A GNU Manual,'' +and with the Back-Cover Texts as in (a) below. A copy of the license +is included in the section entitled ``GNU Free Documentation License.'' + +(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and +modify this GNU manual. Buying copies from the FSF supports it in +developing GNU and promoting software freedom.'' + +This document is part of a collection distributed under the GNU Free +Documentation License. If you want to distribute this document +separately from the collection, you can do so by adding a copy of the +license to the document, as described in section 6 of the license. +@end quotation +@end copying + +@dircategory Emacs +@direntry +* Org Mode Guide: (orgguide). Abbreviated Org-mode Manual +@end direntry + +@titlepage +@title The compact Org-mode Guide + +@subtitle Release @value{VERSION} +@author by Carsten Dominik + +@c The following two commands start the copyright page. +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@c Output the table of contents at the beginning. +@shortcontents + +@ifnottex +@node Top, Introduction, (dir), (dir) +@top Org Mode Manual + +@insertcopying +@end ifnottex + +@menu +* Introduction:: Getting started +* Document Structure:: A tree works like your brain +* Tables:: Pure magic for quick formatting +* Hyperlinks:: Notes in context +* TODO Items:: Every tree branch can be a TODO item +* Tags:: Tagging headlines and matching sets of tags +* Properties:: +* Dates and Times:: Making items useful for planning +* Capture - Refile - Archive:: The ins and outs for projects +* Agenda Views:: Collecting information into views +* Markup:: Prepare text for rich export +* Exporting:: Sharing and publishing of notes +* Publishing:: Create a web site of linked Org files +* Miscellaneous:: All the rest which did not fit elsewhere + +@detailmenu + --- The Detailed Node Listing --- + +Introduction + +* Preface:: Welcome +* Installation:: How to install a downloaded version of Org +* Activation:: How to activate Org for certain buffers +* Feedback:: Bug reports, ideas, patches etc. + +Document Structure + +* Outlines:: Org is based on Outline mode +* Headlines:: How to typeset Org tree headlines +* Visibility cycling:: Show and hide, much simplified +* Motion:: Jumping to other headlines +* Structure editing:: Changing sequence and level of headlines +* Sparse trees:: Matches embedded in context +* Plain lists:: Additional structure within an entry +* Footnotes:: How footnotes are defined in Org's syntax + +Hyperlinks + +* Link format:: How links in Org are formatted +* Internal links:: Links to other places in the current file +* External links:: URL-like links to the world +* Handling links:: Creating, inserting and following +* Targeted links:: Point at a location in a file + +TODO Items + +* Using TODO states:: +* Multi-state workflows:: +* Progress logging:: Dates and notes for progress +* Priorities:: Some things are more important than others +* Breaking down tasks:: Splitting a task into manageable pieces +* Checkboxes:: Tick-off lists + +Progress logging + +* Closing items:: When was this entry marked DONE? +* Tracking TODO state changes:: When did the status change? + +Tags + +* Tag inheritance:: Tags use the tree structure of the outline +* Setting tags:: How to assign tags to a headline +* Tag searches:: Searching for combinations of tags + +Dates and Times + +* Timestamps:: Assigning a time to a tree entry +* Creating timestamps:: Commands which insert timestamps +* Deadlines and scheduling:: Planning your work +* Clocking work time:: Tracking how long you spend on a task + +Capture - Refile - Archive + +* Remember:: Capture new tasks/ideas with little interruption +* Refiling notes:: Moving a tree from one place to another +* Archiving:: What to do with finished projects + +Remember + +* Setting up Remember for Org:: Some code for .emacs to get things going +* Remember templates:: Define the outline of different note types +* Storing notes:: Directly get the note to where it belongs + +Agenda Views + +* Agenda files:: Files being searched for agenda information +* Agenda dispatcher:: Keyboard access to agenda views +* Built-in agenda views:: What is available out of the box? +* Agenda commands:: Remote editing of Org trees +* Custom agenda views:: Defining special searches and views + +The built-in agenda views + +* Weekly/daily agenda:: The calendar page with current tasks +* Global TODO list:: All unfinished action items +* Matching tags and properties:: Structured information with fine-tuned search +* Timeline:: Time-sorted view for single file +* Search view:: Find entries by searching for text + +Markup for rich export + +* Structural markup elements:: The basic structure as seen by the exporter +* Images and tables:: Tables and Images will be included +* Literal examples:: Source code examples with special formatting +* Include files:: Include additional files into a document +* Embedded LaTeX:: LaTeX can be freely used inside Org documents + +Structural markup elements + +* Document title:: Where the title is taken from +* Headings and sections:: The document structure as seen by the exporter +* Table of contents:: The if and where of the table of contents +* Paragraphs:: Paragraphs +* Emphasis and monospace:: Bold, italic, etc. +* Comment lines:: What will *not* be exported + +Exporting + +* Export options:: Per-file export settings +* The export dispatcher:: How to access exporter commands +* ASCII/Latin-1/UTF-8 export:: Exporting to flat files with encoding +* HTML export:: Exporting to HTML +* LaTeX and PDF export:: Exporting to La@TeX{}, and processing to PDF +* DocBook export:: Exporting to DocBook +* iCalendar export:: + +Miscellaneous + +* Completion:: M-TAB knows what you need +* Clean view:: Getting rid of leading stars in the outline +* MobileOrg:: Org-mode on the iPhone + +@end detailmenu +@end menu + +@node Introduction, Document Structure, Top, Top +@chapter Introduction + +@menu +* Preface:: Welcome +* Installation:: How to install a downloaded version of Org +* Activation:: How to activate Org for certain buffers +* Feedback:: Bug reports, ideas, patches etc. +@end menu + +@node Preface, Installation, Introduction, Introduction +@section Preface + +Org is a mode for keeping notes, maintaining TODO lists, and doing +project planning with a fast and effective plain-text system. + +@i{This document is an extract from the +@uref{http://orgmode.org/index.html#sec-4_1, comprehensive Org-mode manual}. +It contains all basic features and commands, along with important hints for +customization. It is intended for beginners who would shy back from a 200 +page manual because of sheer size.} + +@node Installation, Activation, Preface, Introduction +@section Installation + +@b{Important:} @i{If you are using a version of Org that is part of the Emacs +distribution or an XEmacs package, please skip this section and go directly +to @ref{Activation}.} + +If you have downloaded Org from the Web, either as a distribution @file{.zip} +or @file{.tar} file, or as a Git archive, it is best to run it directly from +the distribution directory. You need to add @file{lisp} subdirectory to the +Emacs load path. To do this, add the following line to @file{.emacs}: + +@smallexample +(setq load-path (cons "~/path/to/orgdir/lisp" load-path)) +(setq load-path (cons "~/path/to/orgdir/contrib/lisp" load-path)) +@end smallexample + +@noindent For speed you should byte-compile the Lisp files with the shell +command: + +@smallexample +make +@end smallexample + +Then add the following line to @file{.emacs}. It is needed so that +Emacs can autoload functions that are located in files not immediately loaded +when Org-mode starts. +@smalllisp +(require 'org-install) +@end smalllisp + +Do not forget to activate Org as described in the following section. + +@node Activation, Feedback, Installation, Introduction +@section Activation + +Add the following lines to your @file{.emacs} file. The last three lines +define @emph{global} keys for the commands @command{org-store-link}, +@command{org-agenda}, and @command{org-iswitchb}---please choose suitable +keys yourself. + +@smalllisp +;; The following lines are always needed. Choose your own keys. +(add-to-list 'auto-mode-alist '("\\.org\\'" . org-mode)) +(global-font-lock-mode 1) ; for all buffers +(global-set-key "\C-cl" 'org-store-link) +(global-set-key "\C-ca" 'org-agenda) +(global-set-key "\C-cb" 'org-iswitchb) +@end smalllisp + +With this setup, all files with extension @samp{.org} will be put +into Org mode. + +@node Feedback, , Activation, Introduction +@section Feedback + +If you find problems with Org, or if you have questions, remarks, or ideas +about it, please mail to the Org mailing list @email{emacs-orgmode@@gnu.org}. +If you are not a member of the mailing list, your mail will be passed to the +list after a moderator has approved it. For information on how to submit bug +reports, see the main manual. + +@node Document Structure, Tables, Introduction, Top +@chapter Document Structure + +Org is based on Outline mode and provides flexible commands to +edit the structure of the document. + +@menu +* Outlines:: Org is based on Outline mode +* Headlines:: How to typeset Org tree headlines +* Visibility cycling:: Show and hide, much simplified +* Motion:: Jumping to other headlines +* Structure editing:: Changing sequence and level of headlines +* Sparse trees:: Matches embedded in context +* Plain lists:: Additional structure within an entry +* Footnotes:: How footnotes are defined in Org's syntax +@end menu + +@node Outlines, Headlines, Document Structure, Document Structure +@section Outlines + +Org is implemented on top of Outline mode. Outlines allow a +document to be organized in a hierarchical structure, which (at least +for me) is the best representation of notes and thoughts. An overview +of this structure is achieved by folding (hiding) large parts of the +document to show only the general document structure and the parts +currently being worked on. Org greatly simplifies the use of +outlines by compressing the entire show/hide functionality into a single +command, @command{org-cycle}, which is bound to the @key{TAB} key. + +@node Headlines, Visibility cycling, Outlines, Document Structure +@section Headlines + +Headlines define the structure of an outline tree. The headlines in +Org start with one or more stars, on the left margin@footnote{See +the variable @code{org-special-ctrl-a/e} to configure special behavior +of @kbd{C-a} and @kbd{C-e} in headlines.}. For example: + +@smallexample +* Top level headline +** Second level +*** 3rd level + some text +*** 3rd level + more text + +* Another top level headline +@end smallexample + +@noindent Some people find the many stars too noisy and would prefer an +outline that has whitespace followed by a single star as headline +starters. @ref{Clean view}, describes a setup to realize this. + +@node Visibility cycling, Motion, Headlines, Document Structure +@section Visibility cycling + +Outlines make it possible to hide parts of the text in the buffer. +Org uses just two commands, bound to @key{TAB} and +@kbd{S-@key{TAB}} to change the visibility in the buffer. + +@table @kbd +@item @key{TAB} +@emph{Subtree cycling}: Rotate current subtree among the states + +@smallexample +,-> FOLDED -> CHILDREN -> SUBTREE --. +'-----------------------------------' +@end smallexample + +When called with a prefix argument (@kbd{C-u @key{TAB}}) or with the shift +key, global cycling is invoked. + +@item S-@key{TAB} @r{and} C-u @key{TAB} +@emph{Global cycling}: Rotate the entire buffer among the states + +@smallexample +,-> OVERVIEW -> CONTENTS -> SHOW ALL --. +'--------------------------------------' +@end smallexample + +@item C-u C-u C-u @key{TAB} +Show all, including drawers. +@end table + +When Emacs first visits an Org file, the global state is set to +OVERVIEW, i.e. only the top level headlines are visible. This can be +configured through the variable @code{org-startup-folded}, or on a +per-file basis by adding a startup keyword @code{overview}, @code{content}, +@code{showall}, like this: + +@smallexample +#+STARTUP: content +@end smallexample + + +@node Motion, Structure editing, Visibility cycling, Document Structure +@section Motion +The following commands jump to other headlines in the buffer. + +@table @kbd +@item C-c C-n +Next heading. +@item C-c C-p +Previous heading. +@item C-c C-f +Next heading same level. +@item C-c C-b +Previous heading same level. +@item C-c C-u +Backward to higher level heading. +@end table + +@node Structure editing, Sparse trees, Motion, Document Structure +@section Structure editing + +@table @kbd +@item M-@key{RET} +Insert new heading with same level as current. If the cursor is in a plain +list item, a new item is created (@pxref{Plain lists}). When this command is +used in the middle of a line, the line is split and the rest of the line +becomes the new headline@footnote{If you do not want the line to be split, +customize the variable @code{org-M-RET-may-split-line}.}. +@item M-S-@key{RET} +Insert new TODO entry with same level as current heading. +@item @key{TAB} @r{in new, empty entry} +In a new entry with no text yet, @key{TAB} will cycle through reasonable +levels. +@item M-@key{left}@r{/}@key{right} +Promote/demote current heading by one level. +@item M-S-@key{left}@r{/}@key{right} +Promote/demote the current subtree by one level. +@item M-S-@key{up}@r{/}@key{down} +Move subtree up/down (swap with previous/next subtree of same +level). +@item C-c C-w +Refile entry or region to a different location. @xref{Refiling notes}. +@item C-x n s/w +Narrow buffer to current subtree / widen it again +@end table + +When there is an active region (Transient Mark mode), promotion and +demotion work on all headlines in the region. + +@node Sparse trees, Plain lists, Structure editing, Document Structure +@section Sparse trees + +An important feature of Org mode is the ability to construct @emph{sparse +trees} for selected information in an outline tree, so that the entire +document is folded as much as possible, but the selected information is made +visible along with the headline structure above it@footnote{See also the +variables @code{org-show-hierarchy-above}, @code{org-show-following-heading}, +@code{org-show-siblings}, and @code{org-show-entry-below} for detailed +control on how much context is shown around each match.}. Just try it out +and you will see immediately how it works. + +Org mode contains several commands creating such trees, all these +commands can be accessed through a dispatcher: + +@table @kbd +@item C-c / +This prompts for an extra key to select a sparse-tree creating command. +@item C-c / r +Occur. Prompts for a regexp and shows a sparse tree with all matches. Each +match is also highlighted; the highlights disappear by pressing @kbd{C-c C-c}. +@end table + +The other sparse tree commands select headings based on TODO keywords, +tags, or properties and will be discussed later in this manual. + +@node Plain lists, Footnotes, Sparse trees, Document Structure +@section Plain lists + +Within an entry of the outline tree, hand-formatted lists can provide +additional structure. They also provide a way to create lists of +checkboxes (@pxref{Checkboxes}). Org supports editing such lists, +and the HTML exporter (@pxref{Exporting}) parses and formats them. + +Org knows ordered lists, unordered lists, and description lists. +@itemize @bullet +@item +@emph{Unordered} list items start with @samp{-}, @samp{+}, or +@samp{*} as bullets. +@item +@emph{Ordered} list items start with @samp{1.} or @samp{1)}. +@item +@emph{Description} list use @samp{ :: } to separate the @emph{term} from the +description. +@end itemize + +Items belonging to the same list must have the same indentation on the first +line. A list ends before the next line that is indented like the +bullet/number, or less. An example: + +@smallexample +@group +** Lord of the Rings + My favorite scenes are (in this order) + 1. The attack of the Rohirrim + 2. Eowyn's fight with the witch king + + this was already my favorite scene in the book + + I really like Miranda Otto. + Important actors in this film are: + - @b{Elijah Wood} :: He plays Frodo + - @b{Sean Austin} :: He plays Sam, Frodo's friend. +@end group +@end smallexample + +The following commands act on items when the cursor is in the first line of +an item (the line with the bullet or number). + +@table @kbd +@item @key{TAB} +Items can be folded just like headline levels. +@item M-@key{RET} +Insert new item at current level. With a prefix argument, force a new +heading (@pxref{Structure editing}). +@item M-S-@key{RET} +Insert a new item with a checkbox (@pxref{Checkboxes}). +@item M-S-@key{up}@r{/}@key{down} +Move the item including subitems up/down (swap with previous/next item +of same indentation). If the list is ordered, renumbering is +automatic. +@item M-@key{left}@r{/}M-@key{right} +Decrease/increase the indentation of an item, leaving children alone. +@item M-S-@key{left}@r{/}@key{right} +Decrease/increase the indentation of the item, including subitems. +@item C-c C-c +If there is a checkbox (@pxref{Checkboxes}) in the item line, toggle the +state of the checkbox. If not, make sure all items have the same bullet type +and renumber ordered lists. +@item C-c - +Cycle the entire list level through the different itemize/enumerate bullets +(@samp{-}, @samp{+}, @samp{*}, @samp{1.}, @samp{1)}). +@end table + +@node Footnotes, , Plain lists, Document Structure +@section Footnotes + +A footnote is defined in a paragraph that is started by a footnote marker in +square brackets in column 0, no indentation allowed. The footnote reference +is simply the marker in square brackets, inside text. For example: + +@smallexample +The Org homepage[fn:1] now looks a lot better than it used to. +... +[fn:1] The link is: http://orgmode.org +@end smallexample + +@noindent The following commands handle footnotes: + +@table @kbd +@item C-c C-x f +The footnote action command. When the cursor is on a footnote reference, +jump to the definition. When it is at a definition, jump to the (first) +reference. Otherwise, create a new footnote. When this command is called +with a prefix argument, a menu of additional options including renumbering is +offered. + +@item C-c C-c +Jump between definition and reference. +@end table + +@seealso{ +@uref{http://orgmode.org/manual/Document-Structure.html#Document-Structure, +Chapter 2 of the manual}@* +@uref{http://sachachua.com/wp/2008/01/outlining-your-notes-with-org/, +Sacha Chua's tutorial}} + + +@node Tables, Hyperlinks, Document Structure, Top +@chapter Tables + +Org comes with a fast and intuitive table editor. Spreadsheet-like +calculations are supported in connection with the Emacs @file{calc} +package +@ifinfo +(@pxref{Top,Calc,,Calc,Gnu Emacs Calculator Manual}). +@end ifinfo +@ifnotinfo +(see the Emacs Calculator manual for more information about the Emacs +calculator). +@end ifnotinfo + +Org makes it easy to format tables in plain ASCII. Any line with +@samp{|} as the first non-whitespace character is considered part of a +table. @samp{|} is also the column separator. A table might look like +this: + +@smallexample +| Name | Phone | Age | +|-------+-------+-----| +| Peter | 1234 | 17 | +| Anna | 4321 | 25 | +@end smallexample + +A table is re-aligned automatically each time you press @key{TAB} or +@key{RET} or @kbd{C-c C-c} inside the table. @key{TAB} also moves to +the next field (@key{RET} to the next row) and creates new table rows +at the end of the table or before horizontal lines. The indentation +of the table is set by the first line. Any line starting with +@samp{|-} is considered as a horizontal separator line and will be +expanded on the next re-align to span the whole table width. So, to +create the above table, you would only type + +@smallexample +|Name|Phone|Age| +|- +@end smallexample + +@noindent and then press @key{TAB} to align the table and start filling in +fields. Even faster would be to type @code{|Name|Phone|Age} followed by +@kbd{C-c @key{RET}}. + +When typing text into a field, Org treats @key{DEL}, +@key{Backspace}, and all character keys in a special way, so that +inserting and deleting avoids shifting other fields. Also, when +typing @emph{immediately after the cursor was moved into a new field +with @kbd{@key{TAB}}, @kbd{S-@key{TAB}} or @kbd{@key{RET}}}, the +field is automatically made blank. + +@table @kbd +@tsubheading{Creation and conversion} +@item C-c | +Convert the active region to table. If every line contains at least one +TAB character, the function assumes that the material is tab separated. +If every line contains a comma, comma-separated values (CSV) are assumed. +If not, lines are split at whitespace into fields. +@* +If there is no active region, this command creates an empty Org +table. But it's easier just to start typing, like +@kbd{|Name|Phone|Age C-c @key{RET}}. + +@tsubheading{Re-aligning and field motion} +@item C-c C-c +Re-align the table without moving the cursor. +@c +@item @key{TAB} +Re-align the table, move to the next field. Creates a new row if +necessary. +@c +@item S-@key{TAB} +Re-align, move to previous field. +@c +@item @key{RET} +Re-align the table and move down to next row. Creates a new row if +necessary. + +@tsubheading{Column and row editing} +@item M-@key{left} +@itemx M-@key{right} +Move the current column left/right. +@c +@item M-S-@key{left} +Kill the current column. +@c +@item M-S-@key{right} +Insert a new column to the left of the cursor position. +@c +@item M-@key{up} +@itemx M-@key{down} +Move the current row up/down. +@c +@item M-S-@key{up} +Kill the current row or horizontal line. +@c +@item M-S-@key{down} +Insert a new row above the current row. With a prefix argument, the line is +created below the current one. +@c +@item C-c - +Insert a horizontal line below current row. With a prefix argument, the line +is created above the current line. +@c +@item C-c @key{RET} +Insert a horizontal line below current row, and move the cursor into the row +below that line. +@c +@item C-c ^ +Sort the table lines in the region. The position of point indicates the +column to be used for sorting, and the range of lines is the range +between the nearest horizontal separator lines, or the entire table. + +@end table + +@seealso{ +@uref{http://orgmode.org/manual/Tables.html#Tables, Chapter 3 of the +manual}@* +@uref{http://orgmode.org/worg/org-tutorials/tables.php, Bastien's +table tutorial}@* +@uref{http://orgmode.org/worg/org-tutorials/org-spreadsheet-intro.php, +Bastien's spreadsheet tutorial}@* +@uref{http://orgmode.org/worg/org-tutorials/org-plot.php, Eric's plotting tutorial}} + +@node Hyperlinks, TODO Items, Tables, Top +@chapter Hyperlinks + +Like HTML, Org provides links inside a file, external links to +other files, Usenet articles, emails, and much more. + +@menu +* Link format:: How links in Org are formatted +* Internal links:: Links to other places in the current file +* External links:: URL-like links to the world +* Handling links:: Creating, inserting and following +* Targeted links:: Point at a location in a file +@end menu + +@node Link format, Internal links, Hyperlinks, Hyperlinks +@section Link format + +Org will recognize plain URL-like links and activate them as +clickable links. The general link format, however, looks like this: + +@smallexample +[[link][description]] @r{or alternatively} [[link]] +@end smallexample + +@noindent +Once a link in the buffer is complete (all brackets present), Org will change +the display so that @samp{description} is displayed instead of +@samp{[[link][description]]} and @samp{link} is displayed instead of +@samp{[[link]]}. To edit the invisible @samp{link} part, use @kbd{C-c +C-l} with the cursor on the link. + +@node Internal links, External links, Link format, Hyperlinks +@section Internal links + +If the link does not look like a URL, it is considered to be internal in the +current file. The most important case is a link like +@samp{[[#my-custom-id]]} which will link to the entry with the +@code{CUSTOM_ID} property @samp{my-custom-id}. + +Links such as @samp{[[My Target]]} or @samp{[[My Target][Find my target]]} +lead to a text search in the current file for the corresponding target which +looks like @samp{<>}. + +@node External links, Handling links, Internal links, Hyperlinks +@section External links + +Org supports links to files, websites, Usenet and email messages, +BBDB database entries and links to both IRC conversations and their +logs. External links are URL-like locators. They start with a short +identifying string followed by a colon. There can be no space after +the colon. Here are some examples: + +@smallexample +http://www.astro.uva.nl/~dominik @r{on the web} +file:/home/dominik/images/jupiter.jpg @r{file, absolute path} +/home/dominik/images/jupiter.jpg @r{same as above} +file:papers/last.pdf @r{file, relative path} +file:projects.org @r{another Org file} +docview:papers/last.pdf::NNN @r{open file in doc-view mode at page NNN} +id:B7423F4D-2E8A-471B-8810-C40F074717E9 @r{Link to heading by ID} +news:comp.emacs @r{Usenet link} +mailto:adent@@galaxy.net @r{Mail link} +vm:folder @r{VM folder link} +vm:folder#id @r{VM message link} +wl:folder#id @r{WANDERLUST message link} +mhe:folder#id @r{MH-E message link} +rmail:folder#id @r{RMAIL message link} +gnus:group#id @r{Gnus article link} +bbdb:R.*Stallman @r{BBDB link (with regexp)} +irc:/irc.com/#emacs/bob @r{IRC link} +info:org:External%20links @r{Info node link (with encoded space)} +@end smallexample + +A link should be enclosed in double brackets and may contain a +descriptive text to be displayed instead of the URL (@pxref{Link +format}), for example: + +@smallexample +[[http://www.gnu.org/software/emacs/][GNU Emacs]] +@end smallexample + +@noindent +If the description is a file name or URL that points to an image, HTML export +(@pxref{HTML export}) will inline the image as a clickable button. If there +is no description at all and the link points to an image, that image will be +inlined into the exported HTML file. + +@node Handling links, Targeted links, External links, Hyperlinks +@section Handling links + +Org provides methods to create a link in the correct syntax, to +insert it into an Org file, and to follow the link. + +@table @kbd +@item C-c l +Store a link to the current location. This is a @emph{global} command (you +must create the key binding yourself) which can be used in any buffer to +create a link. The link will be stored for later insertion into an Org +buffer (see below). +@c +@item C-c C-l +Insert a link. This prompts for a link to be inserted into the buffer. You +can just type a link, or use history keys @key{up} and @key{down} to access +stored links. You will be prompted for the description part of the link. +When called with a @kbd{C-u} prefix argument, file name completion is used to +link to a file. +@c +@item C-c C-l @r{(with cursor on existing link)} +When the cursor is on an existing link, @kbd{C-c C-l} allows you to edit the +link and description parts of the link. +@c +@item C-c C-o @r{or} mouse-1 @r{or} mouse-2 +Open link at point. +@item C-c & +Jump back to a recorded position. A position is recorded by the +commands following internal links, and by @kbd{C-c %}. Using this +command several times in direct succession moves through a ring of +previously recorded positions. +@c +@end table + +@node Targeted links, , Handling links, Hyperlinks +@section Targeted links + +File links can contain additional information to make Emacs jump to a +particular location in the file when following a link. This can be a +line number or a search option after a double colon. + +Here is the syntax of the different ways to attach a search to a file +link, together with an explanation: + +@smallexample +[[file:~/code/main.c::255]] @r{Find line 255} +[[file:~/xx.org::My Target]] @r{Find @samp{<>}} +[[file:~/xx.org::#my-custom-id]] @r{Find entry with custom id} +@end smallexample + +@seealso{ +@uref{http://orgmode.org/manual/Hyperlinks.html#Hyperlinks, Chapter 4 of the +manual}} + +@node TODO Items, Tags, Hyperlinks, Top +@chapter TODO Items + +Org mode does not maintain TODO lists as separate documents@footnote{Of +course, you can make a document that contains only long lists of TODO items, +but this is not required.}. Instead, TODO items are an integral part of the +notes file, because TODO items usually come up while taking notes! With Org +mode, simply mark any entry in a tree as being a TODO item. In this way, +information is not duplicated, and the entire context from which the TODO +item emerged is always present. + +Of course, this technique for managing TODO items scatters them +throughout your notes file. Org mode compensates for this by providing +methods to give you an overview of all the things that you have to do. + +@menu +* Using TODO states:: +* Multi-state workflows:: +* Progress logging:: Dates and notes for progress +* Priorities:: Some things are more important than others +* Breaking down tasks:: Splitting a task into manageable pieces +* Checkboxes:: Tick-off lists +@end menu + +@node Using TODO states, Multi-state workflows, TODO Items, TODO Items +@section Using TODO states + +Any headline becomes a TODO item when it starts with the word +@samp{TODO}, for example: + +@smallexample +*** TODO Write letter to Sam Fortune +@end smallexample + +@noindent +The most important commands to work with TODO entries are: + +@table @kbd +@item C-c C-t +Rotate the TODO state of the current item among + +@smallexample +,-> (unmarked) -> TODO -> DONE --. +'--------------------------------' +@end smallexample + +The same rotation can also be done ``remotely'' from the timeline and +agenda buffers with the @kbd{t} command key (@pxref{Agenda commands}). + +@item S-@key{right}@r{/}@key{left} +Select the following/preceding TODO state, similar to cycling. +@item C-c / t +View TODO items in a @emph{sparse tree} (@pxref{Sparse trees}). Folds the +buffer, but shows all TODO items and the headings hierarchy above +them. +@item C-c a t +Show the global TODO list. Collects the TODO items from all agenda files +(@pxref{Agenda Views}) into a single buffer. @xref{Global TODO list}, for +more information. +@item S-M-@key{RET} +Insert a new TODO entry below the current one. +@end table + +@noindent +Changing a TODO state can also trigger tag changes. See the docstring of the +option @code{org-todo-state-tags-triggers} for details. + +@node Multi-state workflows, Progress logging, Using TODO states, TODO Items +@section Multi-state workflows + +You can use TODO keywords to indicate different @emph{sequential} states +in the process of working on an item, for example: + +@smalllisp +(setq org-todo-keywords + '((sequence "TODO" "FEEDBACK" "VERIFY" "|" "DONE" "DELEGATED"))) +@end smalllisp + +The vertical bar separates the TODO keywords (states that @emph{need +action}) from the DONE states (which need @emph{no further action}). If +you don't provide the separator bar, the last state is used as the DONE +state. +With this setup, the command @kbd{C-c C-t} will cycle an entry from TODO +to FEEDBACK, then to VERIFY, and finally to DONE and DELEGATED. + +Sometimes you may want to use different sets of TODO keywords in +parallel. For example, you may want to have the basic +@code{TODO}/@code{DONE}, but also a workflow for bug fixing, and a +separate state indicating that an item has been canceled (so it is not +DONE, but also does not require action). Your setup would then look +like this: + +@smalllisp +(setq org-todo-keywords + '((sequence "TODO(t)" "|" "DONE(d)") + (sequence "REPORT(r)" "BUG(b)" "KNOWNCAUSE(k)" "|" "FIXED(f)") + (sequence "|" "CANCELED(c)"))) +@end smalllisp + +The keywords should all be different, this helps Org mode to keep track of +which subsequence should be used for a given entry. The example also shows +how to define keys for fast access of a particular state, by adding a letter +in parenthesis after each keyword - you will be prompted for the key after +@kbd{C-c C-t}. + +To define TODO keywords that are valid only in a single file, use the +following text anywhere in the file. + +@smallexample +#+TODO: TODO(t) | DONE(d) +#+TODO: REPORT(r) BUG(b) KNOWNCAUSE(k) | FIXED(f) +#+TODO: | CANCELED(c) +@end smallexample + +After changing one of these lines, use @kbd{C-c C-c} with the cursor still in +the line to make the changes known to Org mode. + +@node Progress logging, Priorities, Multi-state workflows, TODO Items +@section Progress logging + +Org mode can automatically record a timestamp and possibly a note when +you mark a TODO item as DONE, or even each time you change the state of +a TODO item. This system is highly configurable, settings can be on a +per-keyword basis and can be localized to a file or even a subtree. For +information on how to clock working time for a task, see @ref{Clocking +work time}. + +@menu +* Closing items:: When was this entry marked DONE? +* Tracking TODO state changes:: When did the status change? +@end menu + +@node Closing items, Tracking TODO state changes, Progress logging, Progress logging +@unnumberedsubsec Closing items + +The most basic logging is to keep track of @emph{when} a certain TODO +item was finished. This is achieved with@footnote{The corresponding +in-buffer setting is: @code{#+STARTUP: logdone}}. + +@smalllisp +(setq org-log-done 'time) +@end smalllisp + +@noindent +Then each time you turn an entry from a TODO (not-done) state into any of the +DONE states, a line @samp{CLOSED: [timestamp]} will be inserted just after +the headline. If you want to record a note along with the timestamp, +use@footnote{The corresponding in-buffer setting is: @code{#+STARTUP: +lognotedone}} + +@smalllisp +(setq org-log-done 'note) +@end smalllisp + +@noindent +You will then be prompted for a note, and that note will be stored below +the entry with a @samp{Closing Note} heading. + +@node Tracking TODO state changes, , Closing items, Progress logging +@unnumberedsubsec Tracking TODO state changes + +You might want to keep track of TODO state changes. You can either record +just a timestamp, or a time-stamped note for a change. These records will be +inserted after the headline as an itemized list. When taking a lot of notes, +you might want to get the notes out of the way into a drawer. Customize the +variable @code{org-log-into-drawer} to get this behavior. + +For state logging, Org mode expects configuration on a per-keyword basis. +This is achieved by adding special markers @samp{!} (for a timestamp) and +@samp{@@} (for a note) in parentheses after each keyword. For example: +@smallexample +#+TODO: TODO(t) WAIT(w@@/!) | DONE(d!) CANCELED(c@@) +@end smallexample +@noindent +will define TODO keywords and fast access keys, and also request that a time +is recorded when the entry is set to DONE, and that a note is recorded when +switching to WAIT or CANCELED. The same syntax works also when setting +@code{org-todo-keywords}. + +@node Priorities, Breaking down tasks, Progress logging, TODO Items +@section Priorities + +If you use Org mode extensively, you may end up with enough TODO items that +it starts to make sense to prioritize them. Prioritizing can be done by +placing a @emph{priority cookie} into the headline of a TODO item, like this + +@smallexample +*** TODO [#A] Write letter to Sam Fortune +@end smallexample + +@noindent +Org mode supports three priorities: @samp{A}, @samp{B}, and @samp{C}. +@samp{A} is the highest, @samp{B} the default if none is given. Priorities +make a difference only in the agenda. + +@table @kbd +@item @kbd{C-c ,} +Set the priority of the current headline. Press @samp{A}, @samp{B} or +@samp{C} to select a priority, or @key{SPC} to remove the cookie. +@c +@item S-@key{up} +@itemx S-@key{down} +Increase/decrease priority of current headline +@end table + +@node Breaking down tasks, Checkboxes, Priorities, TODO Items +@section Breaking tasks down into subtasks + +It is often advisable to break down large tasks into smaller, manageable +subtasks. You can do this by creating an outline tree below a TODO item, +with detailed subtasks on the tree. To keep the overview over the fraction +of subtasks that are already completed, insert either @samp{[/]} or +@samp{[%]} anywhere in the headline. These cookies will be updated each time +the TODO status of a child changes, or when pressing @kbd{C-c C-c} on the +cookie. For example: + +@smallexample +* Organize Party [33%] +** TODO Call people [1/2] +*** TODO Peter +*** DONE Sarah +** TODO Buy food +** DONE Talk to neighbor +@end smallexample + +@node Checkboxes, , Breaking down tasks, TODO Items +@section Checkboxes + +Every item in a plain list (@pxref{Plain lists}) can be made into a checkbox +by starting it with the string @samp{[ ]}. Checkboxes are not included into +the global TODO list, so they are often great to split a task into a number +of simple steps. +Here is an example of a checkbox list. + +@smallexample +* TODO Organize party [1/3] + - [-] call people [1/2] + - [ ] Peter + - [X] Sarah + - [X] order food + - [ ] think about what music to play +@end smallexample + +Checkboxes work hierarchically, so if a checkbox item has children that +are checkboxes, toggling one of the children checkboxes will make the +parent checkbox reflect if none, some, or all of the children are +checked. + +@noindent The following commands work with checkboxes: + +@table @kbd +@item C-c C-c +Toggle checkbox status or (with prefix arg) checkbox presence at point. +@item M-S-@key{RET} +Insert a new item with a checkbox. +This works only if the cursor is already in a plain list item +(@pxref{Plain lists}). +@end table + +@seealso{ +@uref{http://orgmode.org/manual/TODO-Items.html#TODO-Items, Chapter 5 of the manual}@* +@uref{http://orgmode.org/worg/org-tutorials/orgtutorial_dto.php, David +O'Toole's introductory tutorial}@* +@uref{http://members.optusnet.com.au/~charles57/GTD/gtd_workflow.html, +Charles Cave's GTD setup}} + +@node Tags, Properties, TODO Items, Top +@chapter Tags + +An excellent way to implement labels and contexts for cross-correlating +information is to assign @i{tags} to headlines. Org mode has extensive +support for tags. + +Every headline can contain a list of tags; they occur at the end of the +headline. Tags are normal words containing letters, numbers, @samp{_}, and +@samp{@@}. Tags must be preceded and followed by a single colon, e.g., +@samp{:work:}. Several tags can be specified, as in @samp{:work:urgent:}. +Tags will by default be in bold face with the same color as the headline. + +@menu +* Tag inheritance:: Tags use the tree structure of the outline +* Setting tags:: How to assign tags to a headline +* Tag searches:: Searching for combinations of tags +@end menu + +@node Tag inheritance, Setting tags, Tags, Tags +@section Tag inheritance + +@i{Tags} make use of the hierarchical structure of outline trees. If a +heading has a certain tag, all subheadings will inherit the tag as +well. For example, in the list + +@smallexample +* Meeting with the French group :work: +** Summary by Frank :boss:notes: +*** TODO Prepare slides for him :action: +@end smallexample + +@noindent +the final heading will have the tags @samp{:work:}, @samp{:boss:}, +@samp{:notes:}, and @samp{:action:} even though the final heading is not +explicitly marked with those tags. You can also set tags that all entries in +a file should inherit just as if these tags were defined in a hypothetical +level zero that surrounds the entire file. Use a line like this@footnote{As +with all these in-buffer settings, pressing @kbd{C-c C-c} activates any +changes in the line.}: + +@smallexample +#+FILETAGS: :Peter:Boss:Secret: +@end smallexample + +@node Setting tags, Tag searches, Tag inheritance, Tags +@section Setting tags + +Tags can simply be typed into the buffer at the end of a headline. +After a colon, @kbd{M-@key{TAB}} offers completion on tags. There is +also a special command for inserting tags: + +@table @kbd +@item C-c C-q +Enter new tags for the current headline. Org mode will either offer +completion or a special single-key interface for setting tags, see +below. After pressing @key{RET}, the tags will be inserted and aligned +to @code{org-tags-column}. When called with a @kbd{C-u} prefix, all +tags in the current buffer will be aligned to that column, just to make +things look nice. +@item C-c C-c +When the cursor is in a headline, this does the same as @kbd{C-c C-q}. +@end table + +Org will support tag insertion based on a @emph{list of tags}. By +default this list is constructed dynamically, containing all tags +currently used in the buffer. You may also globally specify a hard list +of tags with the variable @code{org-tag-alist}. Finally you can set +the default tags for a given file with lines like + +@smallexample +#+TAGS: @@work @@home @@tennisclub +#+TAGS: laptop car pc sailboat +@end smallexample + +By default Org mode uses the standard minibuffer completion facilities for +entering tags. However, it also implements another, quicker, tag selection +method called @emph{fast tag selection}. This allows you to select and +deselect tags with just a single key press. For this to work well you should +assign unique letters to most of your commonly used tags. You can do this +globally by configuring the variable @code{org-tag-alist} in your +@file{.emacs} file. For example, you may find the need to tag many items in +different files with @samp{:@@home:}. In this case you can set something +like: + +@smalllisp +(setq org-tag-alist '(("@@work" . ?w) ("@@home" . ?h) ("laptop" . ?l))) +@end smalllisp + +@noindent If the tag is only relevant to the file you are working on, then you +can instead set the TAGS option line as: + +@smallexample +#+TAGS: @@work(w) @@home(h) @@tennisclub(t) laptop(l) pc(p) +@end smallexample + +@node Tag searches, , Setting tags, Tags +@section Tag searches + +Once a system of tags has been set up, it can be used to collect related +information into special lists. + +@table @kbd +@item C-c \ +@itemx C-c / m +Create a sparse tree with all headlines matching a tags search. With a +@kbd{C-u} prefix argument, ignore headlines that are not a TODO line. +@item C-c a m +Create a global list of tag matches from all agenda files. +@xref{Matching tags and properties}. +@item C-c a M +Create a global list of tag matches from all agenda files, but check +only TODO items and force checking subitems (see variable +@code{org-tags-match-list-sublevels}). +@end table + +These commands all prompt for a match string which allows basic Boolean logic +like @samp{+boss+urgent-project1}, to find entries with tags @samp{boss} and +@samp{urgent}, but not @samp{project1}, or @samp{Kathy|Sally} to find entries +which are tagged, like @samp{Kathy} or @samp{Sally}. The full syntax of the +search string is rich and allows also matching against TODO keywords, entry +levels and properties. For a complete description with many examples, see +@ref{Matching tags and properties}. + +@seealso{ +@uref{http://orgmode.org/manual/Tags.html#Tags, Chapter 6 of the manual}@* +@uref{http://sachachua.com/wp/2008/01/tagging-in-org-plus-bonus-code-for-timeclocks-and-tags/, +Sacha Chua's article about tagging in Org-mode}} + +@node Properties, Dates and Times, Tags, Top +@chapter Properties + +Properties are key-value pairs associates with and entry. They live in a +special drawer with the name @code{PROPERTIES}. Each +property is specified on a single line, with the key (surrounded by colons) +first, and the value after it: + +@smallexample +* CD collection +** Classic +*** Goldberg Variations + :PROPERTIES: + :Title: Goldberg Variations + :Composer: J.S. Bach + :Publisher: Deutsche Grammophon + :NDisks: 1 + :END: +@end smallexample + +You may define the allowed values for a particular property @samp{:Xyz:} +by setting a property @samp{:Xyz_ALL:}. This special property is +@emph{inherited}, so if you set it in a level 1 entry, it will apply to +the entire tree. When allowed values are defined, setting the +corresponding property becomes easier and is less prone to typing +errors. For the example with the CD collection, we can predefine +publishers and the number of disks in a box like this: + +@smallexample +* CD collection + :PROPERTIES: + :NDisks_ALL: 1 2 3 4 + :Publisher_ALL: "Deutsche Grammophon" Philips EMI + :END: +@end smallexample +or globally using @code{org-global-properties}, or file-wide like this: +@smallexample +#+PROPERTY: NDisks_ALL 1 2 3 4 +@end smallexample + +@table @kbd +@item C-c C-x p +Set a property. This prompts for a property name and a value. +@item C-c C-c d +Remove a property from the current entry. +@end table + +To create sparse trees and special lists with selection based on properties, +the same commands are used as for tag searches (@pxref{Tag searches}). The +syntax for the search string is described in @ref{Matching tags and +properties}. + +@table @kbd +@end table + +@seealso{ +@uref{http://orgmode.org/manual/Properties-and-Columns.html#Properties-and-Columns, +Chapter 7 of the manual}@* +@uref{http://orgmode.org/worg/org-tutorials/org-column-view-tutorial.php,Bastien +Guerry's column view tutorial}} + +@node Dates and Times, Capture - Refile - Archive, Properties, Top +@chapter Dates and Times + +To assist project planning, TODO items can be labeled with a date and/or +a time. The specially formatted string carrying the date and time +information is called a @emph{timestamp} in Org mode. + +@menu +* Timestamps:: Assigning a time to a tree entry +* Creating timestamps:: Commands which insert timestamps +* Deadlines and scheduling:: Planning your work +* Clocking work time:: Tracking how long you spend on a task +@end menu + + +@node Timestamps, Creating timestamps, Dates and Times, Dates and Times +@section Timestamps + +A timestamp is a specification of a date (possibly with a time or a range of +times) in a special format, either @samp{<2003-09-16 Tue>} or +@samp{<2003-09-16 Tue 09:39>} or @samp{<2003-09-16 Tue 12:00-12:30>}. A +timestamp can appear anywhere in the headline or body of an Org tree entry. +Its presence causes entries to be shown on specific dates in the agenda +(@pxref{Weekly/daily agenda}). We distinguish: + +@noindent @b{Plain timestamp; Event; Appointment}@* +A simple timestamp just assigns a date/time to an item. This is just +like writing down an appointment or event in a paper agenda. + +@smallexample +* Meet Peter at the movies <2006-11-01 Wed 19:15> +* Discussion on climate change <2006-11-02 Thu 20:00-22:00> +@end smallexample + +@noindent @b{Timestamp with repeater interval}@* +A timestamp may contain a @emph{repeater interval}, indicating that it +applies not only on the given date, but again and again after a certain +interval of N days (d), weeks (w), months (m), or years (y). The +following will show up in the agenda every Wednesday: +@smallexample +* Pick up Sam at school <2007-05-16 Wed 12:30 +1w> +@end smallexample + +@noindent @b{Diary-style sexp entries}@* +For more complex date specifications, Org mode supports using the +special sexp diary entries implemented in the Emacs calendar/diary +package. For example +@smallexample +* The nerd meeting on every 2nd Thursday of the month + <%%(diary-float t 4 2)> +@end smallexample + +@noindent @b{Time/Date range}@* +Two timestamps connected by @samp{--} denote a range. +@smallexample +** Meeting in Amsterdam + <2004-08-23 Mon>--<2004-08-26 Thu> +@end smallexample + +@noindent @b{Inactive timestamp}@* +Just like a plain timestamp, but with square brackets instead of +angular ones. These timestamps are inactive in the sense that they do +@emph{not} trigger an entry to show up in the agenda. + +@smallexample +* Gillian comes late for the fifth time [2006-11-01 Wed] +@end smallexample + + +@node Creating timestamps, Deadlines and scheduling, Timestamps, Dates and Times +@section Creating timestamps + +For Org mode to recognize timestamps, they need to be in the specific +format. All commands listed below produce timestamps in the correct +format. + +@table @kbd +@item C-c . +Prompt for a date and insert a corresponding timestamp. When the cursor is +at an existing timestamp in the buffer, the command is used to modify this +timestamp instead of inserting a new one. When this command is used twice in +succession, a time range is inserted. With a prefix, also add the current +time. +@c +@item C-c ! +Like @kbd{C-c .}, but insert an inactive timestamp that will not cause +an agenda entry. +@c +@item S-@key{left}@r{/}@key{right} +Change date at cursor by one day. +@c +@item S-@key{up}@r{/}@key{down} +Change the item under the cursor in a timestamp. The cursor can be on a +year, month, day, hour or minute. When the timestamp contains a time range +like @samp{15:30-16:30}, modifying the first time will also shift the second, +shifting the time block with constant length. To change the length, modify +the second time. +@end table + +When Org mode prompts for a date/time, it will accept any string containing +some date and/or time information, and intelligently interpret the string, +deriving defaults for unspecified information from the current date and time. +You can also select a date in the pop-up calendar. See the manual for more +information on how exactly the date/time prompt works. + +@node Deadlines and scheduling, Clocking work time, Creating timestamps, Dates and Times +@section Deadlines and scheduling + +A timestamp may be preceded by special keywords to facilitate planning: + +@noindent @b{DEADLINE}@* +Meaning: the task (most likely a TODO item, though not necessarily) is supposed +to be finished on that date. +@table @kbd +@item C-c C-d +Insert @samp{DEADLINE} keyword along with a stamp, in the line following the +headline. +@end table + +On the deadline date, the task will be listed in the agenda. In +addition, the agenda for @emph{today} will carry a warning about the +approaching or missed deadline, starting +@code{org-deadline-warning-days} before the due date, and continuing +until the entry is marked DONE. An example: + +@smallexample +*** TODO write article about the Earth for the Guide + The editor in charge is [[bbdb:Ford Prefect]] + DEADLINE: <2004-02-29 Sun> +@end smallexample + + +@noindent @b{SCHEDULED}@* +Meaning: you are @i{planning to start working} on that task on the given +date@footnote{This is quite different from what is normally understood by +@i{scheduling a meeting}, which is done in Org-mode by just inserting a time +stamp without keyword.}. + +@table @kbd +@item C-c C-s +Insert @samp{SCHEDULED} keyword along with a stamp, in the line following the +headline. +@end table + +The headline will be listed under the given date@footnote{It will still +be listed on that date after it has been marked DONE. If you don't like +this, set the variable @code{org-agenda-skip-scheduled-if-done}.}. In +addition, a reminder that the scheduled date has passed will be present +in the compilation for @emph{today}, until the entry is marked DONE. +I.e. the task will automatically be forwarded until completed. + +@smallexample +*** TODO Call Trillian for a date on New Years Eve. + SCHEDULED: <2004-12-25 Sat> +@end smallexample + +Some tasks need to be repeated again and again. Org mode helps to +organize such tasks using a so-called repeater in a DEADLINE, SCHEDULED, +or plain timestamp. In the following example +@smallexample +** TODO Pay the rent + DEADLINE: <2005-10-01 Sat +1m> +@end smallexample +@noindent +the @code{+1m} is a repeater; the intended interpretation is that the task +has a deadline on <2005-10-01> and repeats itself every (one) month starting +from that time. + +@node Clocking work time, , Deadlines and scheduling, Dates and Times +@section Clocking work time + +Org mode allows you to clock the time you spend on specific tasks in a +project. + +@table @kbd +@item C-c C-x C-i +Start the clock on the current item (clock-in). This inserts the CLOCK +keyword together with a timestamp. When called with a @kbd{C-u} prefix +argument, select the task from a list of recently clocked tasks. +@c +@item C-c C-x C-o +Stop the clock (clock-out). This inserts another timestamp at the same +location where the clock was last started. It also directly computes +the resulting time in inserts it after the time range as @samp{=> +HH:MM}. +@item C-c C-x C-e +Update the effort estimate for the current clock task. +@item C-c C-x C-x +Cancel the current clock. This is useful if a clock was started by +mistake, or if you ended up working on something else. +@item C-c C-x C-j +Jump to the entry that contains the currently running clock. With a +@kbd{C-u} prefix arg, select the target task from a list of recently clocked +tasks. +@item C-c C-x C-r +Insert a dynamic block containing a clock +report as an Org-mode table into the current file. When the cursor is +at an existing clock table, just update it. +@smallexample +#+BEGIN: clocktable :maxlevel 2 :emphasize nil :scope file +#+END: clocktable +@end smallexample +@noindent +For details about how to customize this view, see @uref{http://orgmode.org/manual/Clocking-work-time.html#Clocking-work-time,the manual}. +@item C-c C-c +Update dynamic block at point. The cursor needs to be in the +@code{#+BEGIN} line of the dynamic block. +@end table + +The @kbd{l} key may be used in the timeline (@pxref{Timeline}) and in +the agenda (@pxref{Weekly/daily agenda}) to show which tasks have been +worked on or closed during a day. + +@seealso{ +@uref{http://orgmode.org/manual/Dates-and-Times.html#Dates-and-Times, +Chapter 8 of the manual}@* +@uref{http://members.optusnet.com.au/~charles57/GTD/org_dates/, Charles +Cave's Date and Time tutorial}@* +@uref{http://doc.norang.ca/org-mode.html#Clocking, Bernt Hansen's clocking workflow}} + +@node Capture - Refile - Archive, Agenda Views, Dates and Times, Top +@chapter Capture - Refile - Archive + +An important part of any organization system is the ability to quickly +capture new ideas and tasks, and to associate reference material with them. +Org uses the @file{remember.el} package to create tasks, and stores files +related to a task (@i{attachments}) in a special directory. Once in the +system, tasks and projects need to be moved around. Moving completed project +trees to an archive file keeps the system compact and fast. + +@menu +* Remember:: Capture new tasks/ideas with little interruption +* Refiling notes:: Moving a tree from one place to another +* Archiving:: What to do with finished projects +@end menu + +@node Remember, Refiling notes, Capture - Refile - Archive, Capture - Refile - Archive +@section Remember + +The Remember package by John Wiegley lets you store quick notes with little +interruption of your work flow. It is an excellent way to add new notes and +tasks to Org files. The @code{remember.el} package is part of Emacs 23, not +Emacs 22. See @uref{http://www.emacswiki.org/cgi-bin/wiki/RememberMode} for +more information. + +Org significantly expands the possibilities of Remember: you may define +templates for different note types, and associate target files and headlines +with specific templates. It also allows you to select the location where a +note should be stored interactively, on the fly. + +@menu +* Setting up Remember for Org:: Some code for .emacs to get things going +* Remember templates:: Define the outline of different note types +* Storing notes:: Directly get the note to where it belongs +@end menu + +@node Setting up Remember for Org, Remember templates, Remember, Remember +@unnumberedsubsec Setting up Remember for Org + +The following customization will tell Remember to use Org files as +target, and to create annotations compatible with Org links. + +@smallexample +(org-remember-insinuate) +(setq org-directory "~/path/to/my/orgfiles/") +(setq org-default-notes-file (concat org-directory "/notes.org")) +(define-key global-map "\C-cr" 'org-remember) +@end smallexample + +@noindent +The last line binds the command @code{org-remember} to a global +key@footnote{Please select your own key, @kbd{C-c r} is only a +suggestion.}. @code{org-remember} basically just calls Remember, +but it makes a few things easier: if there is an active region, it will +automatically copy the region into the Remember buffer. It also allows +to jump to the buffer and location where Remember notes are being +stored: just call @code{org-remember} with a prefix argument. If you +use two prefix arguments, Org jumps to the location where the last +remember note was stored. + +@node Remember templates, Storing notes, Setting up Remember for Org, Remember +@unnumberedsubsec Remember templates + +In combination with Org, you can use templates to generate +different types of Remember notes. For example, if you would like +to use one template to create general TODO entries, another one for +journal entries, and a third one for collecting random ideas, you could +use: + +@smallexample +(setq org-remember-templates + '(("Todo" ?t "* TODO %?\n %i\n %a" "~/org/TODO.org" "Tasks") + ("Journal" ?j "* %U %?\n\n %i\n %a" "~/org/JOURNAL.org") + ("Idea" ?i "* %^@{Title@}\n %i\n %a" "~/org/JOURNAL.org" "New Ideas"))) +@end smallexample + +@noindent In these entries, the first string is just a name, and the +character specifies how to select the template. It is useful if the +character is also the first letter of the name. The next string specifies +the template. Two more (optional) strings give the file in which, and the +headline under which, the new note should be stored. + +When you call @kbd{M-x org-remember} (or @kbd{M-x remember}) to remember +something, Org will prompt for a key to select the template (if you have +more than one template) and then prepare the buffer like +@smallexample +* TODO + [[file:@var{link to where you called remember}]] +@end smallexample + +@noindent +During expansion of the template, special @kbd{%}-escapes@footnote{If you +need one of these sequences literally, escape the @kbd{%} with a backslash.} +allow dynamic insertion of content. Here is a small selection of the +possibilities, consult the manual for more. +@smallexample +%a @r{annotation, normally the link created with @code{org-store-link}} +%i @r{initial content, the region when remember is called with C-u.} +%t @r{timestamp, date only} +%T @r{timestamp with date and time} +%u, %U @r{like the above, but inactive timestamps} +@end smallexample + +@node Storing notes, , Remember templates, Remember +@unnumberedsubsec Storing notes + +When you are finished preparing a note with Remember, you have to press +@kbd{C-c C-c} to file the note away. + +The handler will store the note in the file and under the headline +specified in the template, or it will use the default file and headline. The +window configuration will be restored, sending you back to the working +context before the call to Remember. + +@node Refiling notes, Archiving, Remember, Capture - Refile - Archive +@section Refiling notes + +When reviewing the captured data, you may want to refile some of the entries +into a different list, for example into a project. Cutting, finding the +right location, and then pasting the note is cumbersome. To simplify this +process, you can use the following special command: + +@table @kbd +@item C-c C-w +Refile the entry or region at point. This command offers possible locations +for refiling the entry and lets you select one with completion. The item (or +all items in the region) is filed below the target heading as a subitem.@* +By default, all level 1 headlines in the current buffer are considered to be +targets, but you can have more complex definitions across a number of files. +See the variable @code{org-refile-targets} for details. +@item C-u C-c C-w +Use the refile interface to jump to a heading. +@item C-u C-u C-c C-w +Jump to the location where @code{org-refile} last moved a tree to. +@end table + +@node Archiving, , Refiling notes, Capture - Refile - Archive +@section Archiving + +When a project represented by a (sub)tree is finished, you may want +to move the tree out of the way and to stop it from contributing to the +agenda. Archiving is important to keep your working files compact and global +searches like the construction of agenda views fast. +The most common archiving action is to move a project tree to another file, +the archive file. + +@table @kbd +@item C-c C-x C-a +Archive the current entry using the command specified in the variable +@code{org-archive-default-command}. +@item C-c C-x C-s@ @r{or short} @ C-c $ +Archive the subtree starting at the cursor position to the location +given by @code{org-archive-location}. +@end table + +The default archive location is a file in the same directory as the +current file, with the name derived by appending @file{_archive} to the +current file name. For information and examples on how to change this, +see the documentation string of the variable +@code{org-archive-location}. There is also an in-buffer option for +setting this variable, for example + +@smallexample +#+ARCHIVE: %s_done:: +@end smallexample + +@seealso{ +@uref{http://orgmode.org/manual/Capture-_002d-Refile-_002d-Archive.html#Capture-_002d-Refile-_002d-Archive, +Chapter 9 of the manual}@* +@uref{http://members.optusnet.com.au/~charles57/GTD/remember.html, Charles +Cave's remember tutorial}@* +@uref{http://orgmode.org/worg/org-tutorials/org-protocol-custom-handler.php, +Sebastian Rose's tutorial for capturing from a web browser}}@uref{}@* + +@node Agenda Views, Markup, Capture - Refile - Archive, Top +@chapter Agenda Views + +Due to the way Org works, TODO items, time-stamped items, and tagged +headlines can be scattered throughout a file or even a number of files. To +get an overview of open action items, or of events that are important for a +particular date, this information must be collected, sorted and displayed in +an organized way. There are several different views, see below. + +The extracted information is displayed in a special @emph{agenda buffer}. +This buffer is read-only, but provides commands to visit the corresponding +locations in the original Org files, and even to edit these files remotely. +Remote editing from the agenda buffer means, for example, that you can +change the dates of deadlines and appointments from the agenda buffer. +The commands available in the Agenda buffer are listed in @ref{Agenda +commands}. + +@menu +* Agenda files:: Files being searched for agenda information +* Agenda dispatcher:: Keyboard access to agenda views +* Built-in agenda views:: What is available out of the box? +* Agenda commands:: Remote editing of Org trees +* Custom agenda views:: Defining special searches and views +@end menu + +@node Agenda files, Agenda dispatcher, Agenda Views, Agenda Views +@section Agenda files + +The information to be shown is normally collected from all @emph{agenda +files}, the files listed in the variable +@code{org-agenda-files}. + +@table @kbd +@item C-c [ +Add current file to the list of agenda files. The file is added to +the front of the list. If it was already in the list, it is moved to +the front. With a prefix argument, file is added/moved to the end. +@item C-c ] +Remove current file from the list of agenda files. +@item C-, +Cycle through agenda file list, visiting one file after the other. +@end table + +@node Agenda dispatcher, Built-in agenda views, Agenda files, Agenda Views +@section The agenda dispatcher +The views are created through a dispatcher, which should be bound to a +global key---for example @kbd{C-c a} (@pxref{Installation}). After +pressing @kbd{C-c a}, an additional letter is required to execute a +command: +@table @kbd +@item a +The calendar-like agenda (@pxref{Weekly/daily agenda}). +@item t @r{/} T +A list of all TODO items (@pxref{Global TODO list}). +@item m @r{/} M +A list of headlines matching a TAGS expression (@pxref{Matching +tags and properties}). +@item L +The timeline view for the current buffer (@pxref{Timeline}). +@item s +A list of entries selected by a boolean expression of keywords +and/or regular expressions that must or must not occur in the entry. +@end table + +@node Built-in agenda views, Agenda commands, Agenda dispatcher, Agenda Views +@section The built-in agenda views + +@menu +* Weekly/daily agenda:: The calendar page with current tasks +* Global TODO list:: All unfinished action items +* Matching tags and properties:: Structured information with fine-tuned search +* Timeline:: Time-sorted view for single file +* Search view:: Find entries by searching for text +@end menu + +@node Weekly/daily agenda, Global TODO list, Built-in agenda views, Built-in agenda views +@subsection The weekly/daily agenda + +The purpose of the weekly/daily @emph{agenda} is to act like a page of a +paper agenda, showing all the tasks for the current week or day. + +@table @kbd +@item C-c a a +Compile an agenda for the current week from a list of Org files. The agenda +shows the entries for each day. +@end table + +Emacs contains the calendar and diary by Edward M. Reingold. Org-mode +understands the syntax of the diary and allows you to use diary sexp entries +directly in Org files: + +@smallexample +* Birthdays and similar stuff +#+CATEGORY: Holiday +%%(org-calendar-holiday) ; special function for holiday names +#+CATEGORY: Ann +%%(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 +%%(diary-anniversary 10 2 1869) Mahatma Gandhi would be %d years old +@end smallexample + +Org can interact with Emacs appointments notification facility. To add all +the appointments of your agenda files, use the command +@code{org-agenda-to-appt}. See the docstring for details. + +@node Global TODO list, Matching tags and properties, Weekly/daily agenda, Built-in agenda views +@subsection The global TODO list + +The global TODO list contains all unfinished TODO items formatted and +collected into a single place. Remote editing of TODO items lets you +can change the state of a TODO entry with a single key press. The commands +available in the TODO list are described in @ref{Agenda commands}. + +@table @kbd +@item C-c a t +Show the global TODO list. This collects the TODO items from all +agenda files (@pxref{Agenda Views}) into a single buffer. +@item C-c a T +Like the above, but allows selection of a specific TODO keyword. +@end table + +@node Matching tags and properties, Timeline, Global TODO list, Built-in agenda views +@subsection Matching tags and properties + +If headlines in the agenda files are marked with @emph{tags} (@pxref{Tags}), +or have properties (@pxref{Properties}), you can select headlines +based on this metadata and collect them into an agenda buffer. The match +syntax described here also applies when creating sparse trees with @kbd{C-c / +m}. The commands available in the tags list are described in @ref{Agenda +commands}. + +@table @kbd +@item C-c a m +Produce a list of all headlines that match a given set of tags. The +command prompts for a selection criterion, which is a boolean logic +expression with tags, like @samp{+work+urgent-withboss} or +@samp{work|home} (@pxref{Tags}). If you often need a specific search, +define a custom command for it (@pxref{Agenda dispatcher}). +@item C-c a M +Like @kbd{C-c a m}, but only select headlines that are also TODO items. +@end table + +@subsubheading Match syntax + +A search string can use Boolean operators @samp{&} for AND and @samp{|} for +OR. @samp{&} binds more strongly than @samp{|}. Parentheses are currently +not implemented. Each element in the search is either a tag, a regular +expression matching tags, or an expression like @code{PROPERTY OPERATOR +VALUE} with a comparison operator, accessing a property value. Each element +may be preceded by @samp{-}, to select against it, and @samp{+} is syntactic +sugar for positive selection. The AND operator @samp{&} is optional when +@samp{+} or @samp{-} is present. Here are some examples, using only tags. + +@table @samp +@item +work-boss +Select headlines tagged @samp{:work:}, but discard those also tagged +@samp{:boss:}. +@item work|laptop +Selects lines tagged @samp{:work:} or @samp{:laptop:}. +@item work|laptop+night +Like before, but require the @samp{:laptop:} lines to be tagged also +@samp{:night:}. +@end table + +You may also test for properties at the same +time as matching tags, see the manual for more information. + +@node Timeline, Search view, Matching tags and properties, Built-in agenda views +@subsection Timeline for a single file + +The timeline summarizes all time-stamped items from a single Org mode +file in a @emph{time-sorted view}. The main purpose of this command is +to give an overview over events in a project. + +@table @kbd +@item C-c a L +Show a time-sorted view of the Org file, with all time-stamped items. +When called with a @kbd{C-u} prefix, all unfinished TODO entries +(scheduled or not) are also listed under the current date. +@end table + +@node Search view, , Timeline, Built-in agenda views +@subsection Search view + +This agenda view is a general text search facility for Org mode entries. +It is particularly useful to find notes. + +@table @kbd +@item C-c a s +This is a special search that lets you select entries by matching a substring +or specific words using a boolean logic. +@end table +For example, the search string @samp{computer equipment} will find entries +that contain @samp{computer equipment} as a substring. +Search view can also search for specific keywords in the entry, using Boolean +logic. The search string @samp{+computer +wifi -ethernet -@{8\.11[bg]@}} +will search for note entries that contain the keywords @code{computer} +and @code{wifi}, but not the keyword @code{ethernet}, and which are also +not matched by the regular expression @code{8\.11[bg]}, meaning to +exclude both 8.11b and 8.11g. + +Note that in addition to the agenda files, this command will also search +the files listed in @code{org-agenda-text-search-extra-files}. + +@node Agenda commands, Custom agenda views, Built-in agenda views, Agenda Views +@section Commands in the agenda buffer + +Entries in the agenda buffer are linked back to the Org file or diary +file where they originate. Commands are provided to show and jump to the +original entry location, and to edit the Org files ``remotely'' from +the agenda buffer. This is just a selection of the many commands, explore +the @code{Agenda} menu and the manual for a complete list. + +@table @kbd +@tsubheading{Motion} +@item n +Next line (same as @key{up} and @kbd{C-p}). +@item p +Previous line (same as @key{down} and @kbd{C-n}). +@tsubheading{View/Go to Org file} +@item mouse-3 +@itemx @key{SPC} +Display the original location of the item in another window. +With prefix arg, make sure that the entire entry is made visible in the +outline, not only the heading. +@c +@itemx @key{TAB} +Go to the original location of the item in another window. Under Emacs +22, @kbd{mouse-1} will also works for this. +@c +@itemx @key{RET} +Go to the original location of the item and delete other windows. +@c + +@tsubheading{Change display} +@item o +Delete other windows. +@c +@item d @r{/} w +Switch to day/week view. +@c +@item f @r{and} b +Go forward/backward in time to display the following @code{org-agenda-ndays} +days. For example, if the display covers a week, switch to the +following/previous week. +@c +@item . +Go to today. +@c +@item j +Prompt for a date and go there. +@c +@item v l @ @r{or short} @ l +Toggle Logbook mode. In Logbook mode, entries that were marked DONE while +logging was on (variable @code{org-log-done}) are shown in the agenda, as are +entries that have been clocked on that day. When called with a @kbd{C-u} +prefix, show all possible logbook entries, including state changes. +@c +@item r @r{or} g +Recreate the agenda buffer, to reflect the changes. +@item s +Save all Org buffers in the current Emacs session, and also the locations of +IDs. + +@tsubheading{Secondary filtering and query editing} + +@item / +Filter the current agenda view with respect to a tag. You are prompted for a +letter to select a tag. Press @samp{-} first to select against the tag. + +@item \ +Narrow the current agenda filter by an additional condition. + +@tsubheading{Remote editing (see the manual for many more commands)} + +@item 0-9 +Digit argument. +@c +@item t +Change the TODO state of the item, in the agenda and in the +org file. +@c +@item C-k +Delete the current agenda item along with the entire subtree belonging +to it in the original Org file. +@c +@item C-c C-w +Refile the entry at point. +@c +@item C-c C-x C-a @ @r{or short} @ a +Archive the subtree corresponding to the entry at point using the default +archiving command set in @code{org-archive-default-command}. +@c +@item C-c C-x C-s @ @r{or short} @ $ +Archive the subtree corresponding to the current headline. +@c +@item C-c C-s +Schedule this item, with prefix arg remove the scheduling timestamp +@c +@item C-c C-d +Set a deadline for this item, with prefix arg remove the deadline. +@c +@item S-@key{right} @r{and} S-@key{left} +Change the timestamp associated with the current line by one day. +@c +@item I +Start the clock on the current item. +@c +@item O / X +Stop/cancel the previously started clock. + +@item J +Jump to the running clock in another window. +@end table + +@node Custom agenda views, , Agenda commands, Agenda Views +@section Custom agenda views + +The main application of custom searches is the definition of keyboard +shortcuts for frequently used searches, either creating an agenda +buffer, or a sparse tree (the latter covering of course only the current +buffer). +Custom commands are configured in the variable +@code{org-agenda-custom-commands}. You can customize this variable, for +example by pressing @kbd{C-c a C}. You can also directly set it with +Emacs Lisp in @file{.emacs}. The following example contains all valid +search types: + +@smalllisp +@group +(setq org-agenda-custom-commands + '(("w" todo "WAITING") + ("u" tags "+boss-urgent") + ("v" tags-todo "+boss-urgent"))) +@end group +@end smalllisp + +@noindent +The initial string in each entry defines the keys you have to press after the +dispatcher command @kbd{C-c a} in order to access the command. Usually this +will be just a single character. The second parameter is the search type, +followed by the string or regular expression to be used for the matching. +The example above will therefore define: + +@table @kbd +@item C-c a w +as a global search for TODO entries with @samp{WAITING} as the TODO +keyword +@item C-c a u +as a global tags search for headlines marked @samp{:boss:} but not +@samp{:urgent:} +@item C-c a v +as the same search as @kbd{C-c a u}, but limiting the search to +headlines that are also TODO items +@end table + +@seealso{ +@uref{http://orgmode.org/manual/Agenda-Views.html#Agenda-Views, Chapter 10 of +the manual}@* +@uref{http://orgmode.org/worg/org-tutorials/org-custom-agenda-commands.php, +Mat Lundin's tutorial about custom agenda commands}@* +@uref{http://www.newartisans.com/2007/08/using-org-mode-as-a-day-planner.html, +John Wiegley's setup}} + +@node Markup, Exporting, Agenda Views, Top +@chapter Markup for rich export + +When exporting Org-mode documents, the exporter tries to reflect the +structure of the document as accurately as possible in the backend. Since +export targets like HTML, La@TeX{}, or DocBook allow much richer formatting, +Org mode has rules on how to prepare text for rich export. This section +summarizes the markup rules used in an Org-mode buffer. + +@menu +* Structural markup elements:: The basic structure as seen by the exporter +* Images and tables:: Tables and Images will be included +* Literal examples:: Source code examples with special formatting +* Include files:: Include additional files into a document +* Embedded LaTeX:: LaTeX can be freely used inside Org documents +@end menu + +@node Structural markup elements, Images and tables, Markup, Markup +@section Structural markup elements + +@menu +* Document title:: Where the title is taken from +* Headings and sections:: The document structure as seen by the exporter +* Table of contents:: The if and where of the table of contents +* Paragraphs:: Paragraphs +* Emphasis and monospace:: Bold, italic, etc. +* Comment lines:: What will *not* be exported +@end menu + +@node Document title, Headings and sections, Structural markup elements, Structural markup elements +@subheading Document title + +@noindent +The title of the exported document is taken from the special line + +@smallexample +#+TITLE: This is the title of the document +@end smallexample + +@node Headings and sections, Table of contents, Document title, Structural markup elements +@subheading Headings and sections + +The outline structure of the document as described in @ref{Document +Structure}, forms the basis for defining sections of the exported document. +However, since the outline structure is also used for (for example) lists of +tasks, only the first three outline levels will be used as headings. Deeper +levels will become itemized lists. You can change the location of this +switch globally by setting the variable @code{org-export-headline-levels}, or on a +per-file basis with a line + +@smallexample +#+OPTIONS: H:4 +@end smallexample + +@node Table of contents, Paragraphs, Headings and sections, Structural markup elements +@subheading Table of contents + +The table of contents is normally inserted directly before the first headline +of the file. + +@smallexample +#+OPTIONS: toc:2 (only to two levels in TOC) +#+OPTIONS: toc:nil (no TOC at all) +@end smallexample + +@node Paragraphs, Emphasis and monospace, Table of contents, Structural markup elements +@subheading Paragraphs, line breaks, and quoting + +Paragraphs are separated by at least one empty line. If you need to enforce +a line break within a paragraph, use @samp{\\} at the end of a line. + +To keep the line breaks in a region, but otherwise use normal formatting, you +can use this construct, which can also be used to format poetry. + +@smallexample +#+BEGIN_VERSE + Great clouds overhead + Tiny black birds rise and fall + Snow covers Emacs + + -- AlexSchroeder +#+END_VERSE +@end smallexample + +When quoting a passage from another document, it is customary to format this +as a paragraph that is indented on both the left and the right margin. You +can include quotations in Org-mode documents like this: + +@smallexample +#+BEGIN_QUOTE +Everything should be made as simple as possible, +but not any simpler -- Albert Einstein +#+END_QUOTE +@end smallexample + +If you would like to center some text, do it like this: +@smallexample +#+BEGIN_CENTER +Everything should be made as simple as possible, \\ +but not any simpler +#+END_CENTER +@end smallexample + +@node Emphasis and monospace, Comment lines, Paragraphs, Structural markup elements +@subheading Emphasis and monospace + +You can make words @b{*bold*}, @i{/italic/}, _underlined_, @code{=code=} +and @code{~verbatim~}, and, if you must, @samp{+strike-through+}. Text +in the code and verbatim string is not processed for Org-mode specific +syntax, it is exported verbatim. To insert a horizontal rules, use a line +consisting of only dashes, and at least 5 of them. + +@node Comment lines, , Emphasis and monospace, Structural markup elements +@subheading Comment lines + +Lines starting with @samp{#} in column zero are treated as comments and will +never be exported. If you want an indented line to be treated as a comment, +start it with @samp{#+ }. Also entire subtrees starting with the word +@samp{COMMENT} will never be exported. Finally, regions surrounded by +@samp{#+BEGIN_COMMENT} ... @samp{#+END_COMMENT} will not be exported. + +@table @kbd +@item C-c ; +Toggle the COMMENT keyword at the beginning of an entry. +@end table + +@node Images and tables, Literal examples, Structural markup elements, Markup +@section Images and Tables + +For Org mode tables, the lines before the first horizontal separator line +will become table header lines. You can use the following lines somewhere +before the table to assign a caption and a label for cross references, and in +the text you can refer to the object with @code{\ref@{tab:basic-data@}}: + +@smallexample +#+CAPTION: This is the caption for the next table (or link) +#+LABEL: tbl:basic-data + | ... | ...| + |-----|----| +@end smallexample + +Some backends (HTML, La@TeX{}, and DocBook) allow you to directly include +images into the exported document. Org does this, if a link to an image +files does not have a description part, for example @code{[[./img/a.jpg]]}. +If you wish to define a caption for the image and maybe a label for internal +cross references, you sure that the link is on a line by itself precede it +with: + +@smallexample +#+CAPTION: This is the caption for the next figure link (or table) +#+LABEL: fig:SED-HR4049 +[[./img/a.jpg]] +@end smallexample + +You may also define additional attributes for the figure. As this is +backend-specific, see the sections about the individual backends for more +information. + + +@node Literal examples, Include files, Images and tables, Markup +@section Literal examples + +You can include literal examples that should not be subjected to +markup. Such examples will be typeset in monospace, so this is well suited +for source code and similar examples. + +@smallexample +#+BEGIN_EXAMPLE +Some example from a text file. +#+END_EXAMPLE +@end smallexample + +For simplicity when using small examples, you can also start the example +lines with a colon followed by a space. There may also be additional +whitespace before the colon: + +@smallexample +Here is an example + : Some example from a text file. +@end smallexample + +For source code from a programming language, or any other text +that can be marked up by font-lock in Emacs, you can ask for it to +look like the fontified Emacs buffer + +@smallexample +#+BEGIN_SRC emacs-lisp +(defun org-xor (a b) + "Exclusive or." + (if a (not b) b)) +#+END_SRC +@end smallexample + +To edit the example in a special buffer supporting this language, use +@kbd{C-c '} to both enter and leave the editing buffer. + +@node Include files, Embedded LaTeX, Literal examples, Markup +@section Include files + +During export, you can include the content of another file. For example, to +include your @file{.emacs} file, you could use: + +@smallexample +#+INCLUDE: "~/.emacs" src emacs-lisp +@end smallexample +@noindent +The optional second and third parameter are the markup (e.g. @samp{quote}, +@samp{example}, or @samp{src}), and, if the markup is @samp{src}, the +language for formatting the contents. The markup is optional, if it is not +given, the text will be assumed to be in Org mode format and will be +processed normally. @kbd{C-c '} will visit the included file. + +@node Embedded LaTeX, , Include files, Markup +@section Embedded La@TeX{} + +For scientific notes which need to be able to contain mathematical symbols +and the occasional formula, Org-mode supports embedding La@TeX{} code into +its files. You can directly use TeX-like macros for special symbols, enter +formulas and entire LaTeX environments. + +@smallexample +Angles are written as Greek letters \alpha, \beta and \gamma. The mass if +the sun is M_sun = 1.989 x 10^30 kg. The radius of the sun is R_@{sun@} = +6.96 x 10^8 m. If $a^2=b$ and $b=2$, then the solution must be either +$a=+\sqrt@{2@}$ or $a=-\sqrt@{2@}$. + +\begin@{equation@} +x=\sqrt@{b@} +\end@{equation@} +@end smallexample +@noindent With +@uref{http://orgmode.org/manual/LaTeX-fragments.html#LaTeX-fragments,special +setup}, LaTeX snippets will be included as images when exporting to HTML. + +@seealso{ +@uref{http://orgmode.org/manual/Markup.html#Markup, Chapter 11 of the manual}} + +@node Exporting, Publishing, Markup, Top +@chapter Exporting + +Org-mode documents can be exported into a variety of other formats: ASCII +export for inclusion into emails, HTML to publish on the web, La@TeX{}/PDF +for beautiful printed documents and DocBook to enter the world of many other +formats using DocBook tools. There is also export to iCalendar format so +that planning information can be incorporated into desktop calendars. + +@menu +* Export options:: Per-file export settings +* The export dispatcher:: How to access exporter commands +* ASCII/Latin-1/UTF-8 export:: Exporting to flat files with encoding +* HTML export:: Exporting to HTML +* LaTeX and PDF export:: Exporting to La@TeX{}, and processing to PDF +* DocBook export:: Exporting to DocBook +* iCalendar export:: +@end menu + +@node Export options, The export dispatcher, Exporting, Exporting +@section Export options + +The exporter recognizes special lines in the buffer which provide +additional information. These lines may be put anywhere in the file. +The whole set of lines can be inserted into the buffer with @kbd{C-c +C-e t}. + +@table @kbd +@item C-c C-e t +Insert template with export options, see example below. +@end table + +@smallexample +#+TITLE: the title to be shown (default is the buffer name) +#+AUTHOR: the author (default taken from @code{user-full-name}) +#+DATE: a date, fixed, of a format string for @code{format-time-string} +#+EMAIL: his/her email address (default from @code{user-mail-address}) +#+DESCRIPTION: the page description, e.g. for the XHTML meta tag +#+KEYWORDS: the page keywords, e.g. for the XHTML meta tag +#+LANGUAGE: language for HTML, e.g. @samp{en} (@code{org-export-default-language}) +#+TEXT: Some descriptive text to be inserted at the beginning. +#+TEXT: Several lines may be given. +#+OPTIONS: H:2 num:t toc:t \n:nil @@:t ::t |:t ^:t f:t TeX:t ... +#+LINK_UP: the ``up'' link of an exported page +#+LINK_HOME: the ``home'' link of an exported page +#+LATEX_HEADER: extra line(s) for the LaTeX header, like \usepackage@{xyz@} +@end smallexample + +@node The export dispatcher, ASCII/Latin-1/UTF-8 export, Export options, Exporting +@section The export dispatcher + +All export commands can be reached using the export dispatcher, which is a +prefix key that prompts for an additional key specifying the command. +Normally the entire file is exported, but if there is an active region that +contains one outline tree, the first heading is used as document title and +the subtrees are exported. + +@table @kbd +@item C-c C-e +Dispatcher for export and publishing commands. +@end table + +@node ASCII/Latin-1/UTF-8 export, HTML export, The export dispatcher, Exporting +@section ASCII/Latin-1/UTF-8 export + +ASCII export produces a simple and very readable version of an Org-mode +file, containing only plain ASCII. Latin-1 and UTF-8 export augment the file +with special characters and symbols available in these encodings. + +@table @kbd +@item C-c C-e a +Export as ASCII file. +@item C-c C-e n @ @ @r{and} @ @ C-c C-e N +Like the above commands, but use Latin-1 encoding. +@item C-c C-e u @ @ @r{and} @ @ C-c C-e U +Like the above commands, but use UTF-8 encoding. +@end table + +@node HTML export, LaTeX and PDF export, ASCII/Latin-1/UTF-8 export, Exporting +@section HTML export + +@table @kbd +@item C-c C-e h +Export as HTML file @file{myfile.html}. +@item C-c C-e b +Export as HTML file and immediately open it with a browser. +@end table + +To insert HTML that should be copied verbatim to +the exported file use either + +@smallexample +#+HTML: Literal HTML code for export +@end smallexample +@noindent or +@smallexample +#+BEGIN_HTML +All lines between these markers are exported literally +#+END_HTML +@end smallexample + +@node LaTeX and PDF export, DocBook export, HTML export, Exporting +@section La@TeX{} and PDF export + +@table @kbd +@item C-c C-e l +Export as La@TeX{} file @file{myfile.tex}. +@item C-c C-e p +Export as La@TeX{} and then process to PDF. +@item C-c C-e d +Export as La@TeX{} and then process to PDF, then open the resulting PDF file. +@end table + +By default, the La@TeX{} output uses the class @code{article}. You can +change this by adding an option like @code{#+LaTeX_CLASS: myclass} in your +file. The class must be listed in @code{org-export-latex-classes}. + +Embedded La@TeX{} as described in @ref{Embedded LaTeX}, will be correctly +inserted into the La@TeX{} file. Similarly to the HTML exporter, you can use +@code{#+LaTeX:} and @code{#+BEGIN_LaTeX ... #+END_LaTeX} construct to add +verbatim LaTeX code. + +@node DocBook export, iCalendar export, LaTeX and PDF export, Exporting +@section DocBook export + +@table @kbd +@item C-c C-e D +Export as DocBook file. +@end table + +Similarly to the HTML exporter, you can use @code{#+DocBook:} and +@code{#+BEGIN_DocBook ... #+END_DocBook} construct to add verbatim LaTeX +code. + +@node iCalendar export, , DocBook export, Exporting +@section iCalendar export + +@table @kbd +@kindex C-c C-e i +@item C-c C-e i +Create iCalendar entries for the current file in a @file{.ics} file. +@kindex C-c C-e c +@item C-c C-e c +Create a single large iCalendar file from all files in +@code{org-agenda-files} and write it to the file given by +@code{org-combined-agenda-icalendar-file}. +@end table + +@seealso{ +@uref{http://orgmode.org/manual/Exporting.html#Exporting, Chapter 12 of the manual}@* +@uref{http://orgmode.org/worg/org-tutorials/images-and-xhtml-export.php, +Sebastian Rose's image handling tutorial}@* +@uref{http://orgmode.org/worg/org-tutorials/org-latex-export.php, Thomas +Dye's LaTeX export tutorial} +@uref{http://orgmode.org/worg/org-tutorials/org-beamer/tutorial.php, Eric +Fraga's BEAMER presentation tutorial}} + +@node Publishing, Miscellaneous, Exporting, Top +@chapter Publishing + +Org includes a publishing management system that allows you to configure +automatic HTML conversion of @emph{projects} composed of interlinked org +files. You can also configure Org to automatically upload your exported HTML +pages and related attachments, such as images and source code files, to a web +server. For detailed instructions about setup, see the manual. + +Here is an example: + +@smalllisp +(setq org-publish-project-alist + '(("org" + :base-directory "~/org/" + :publishing-directory "~/public_html" + :section-numbers nil + :table-of-contents nil + :style ""))) +@end smalllisp + +@table @kbd +@item C-c C-e C +Prompt for a specific project and publish all files that belong to it. +@item C-c C-e P +Publish the project containing the current file. +@item C-c C-e F +Publish only the current file. +@item C-c C-e E +Publish every project. +@end table + +Org uses timestamps to track when a file has changed. The above functions +normally only publish changed files. You can override this and force +publishing of all files by giving a prefix argument to any of the commands +above. + +@seealso{ +@uref{http://orgmode.org/manual/Publishing.html#Publishing, Chapter 12 of the +manual}@* +@uref{http://orgmode.org/worg/org-tutorials/org-publish-html-tutorial.php, +Sebastian Rose's publishing tutorial}@* +@uref{http://orgmode.org/worg/org-tutorials/org-jekyll.php, Ian Barton's +Jekyll/blogging setup}} + +@node Miscellaneous, , Publishing, Top +@chapter Miscellaneous + +@menu +* Completion:: M-TAB knows what you need +* Clean view:: Getting rid of leading stars in the outline +* MobileOrg:: Org-mode on the iPhone +@end menu + +@node Completion, Clean view, Miscellaneous, Miscellaneous +@section Completion + +Org supports in-buffer completion with @kbd{M-@key{TAB}}. This type of +completion does not make use of the minibuffer. You simply type a few +letters into the buffer and use the key to complete text right there. For +example, this command will complete @TeX{} symbols after @samp{\}, TODO +keywords at the beginning of a headline, and ags after @samp{:} in a +headline. + +@node Clean view, MobileOrg, Completion, Miscellaneous +@section A cleaner outline view + +Some people find it noisy and distracting that the Org headlines start with a +potentially large number of stars, and that text below the headlines is not +indented. While this is no problem when writing a @emph{book-like} document +where the outline headings are really section headings, in a more +@emph{list-oriented} outline, indented structure is a lot cleaner: + +@smallexample +@group +* Top level headline | * Top level headline +** Second level | * Second level +*** 3rd level | * 3rd level +some text | some text +*** 3rd level | * 3rd level +more text | more text +* Another top level headline | * Another top level headline +@end group +@end smallexample + +@noindent +If you are using at least Emacs 23.1.50.3 and version 6.29 of Org, this kind +of view can be achieved dynamically at display time using +@code{org-indent-mode}, which will prepend intangible space to each line. +You can turn on @code{org-indent-mode} for all files by customizing the +variable @code{org-startup-indented}, or you can turn it on for individual +files using + +@smallexample +#+STARTUP: indent +@end smallexample + +If you want a similar effect in earlier version of Emacs and/or Org, or if +you want the indentation to be hard space characters so that the plain text +file looks as similar as possible to the Emacs display, Org supports you by +helping to indent (with @key{TAB}) text below each headline, by hiding +leading stars, and by only using levels 1, 3, etc to get two characters +indentation for each level. To get this support in a file, use + +@smallexample +#+STARTUP: hidestars odd +@end smallexample + +@node MobileOrg, , Clean view, Miscellaneous +@section MobileOrg + +@i{MobileOrg} is an application for the @i{iPhone/iPod Touch} series of +devices, developed by Richard Moreland. For details, see the Org-mode +manual. + +@seealso{ +@uref{http://orgmode.org/manual/Miscellaneous.html#Miscellaneous, Chapter 14 +of the manual}@* +@uref{http://orgmode.org/manual/MobileOrg.html#MobileOrg, Appendix B of the +manual}@* +@uref{http://orgmode.org/orgcard.pdf,Key reference card}} + +@bye + +@ignore + arch-tag: 8f0a8557-0acc-4436-b2b2-0197699e1452 +@end ignore + +@c Local variables: +@c ispell-local-dictionary: "en_US-w_accents" +@c ispell-local-pdict: "./.aspell.org.pws" +@c fill-column: 77 +@c End: + + +@c LocalWords: webdavhost pre -- 2.11.4.GIT