diff options
Diffstat (limited to 'elpa/org-9.5.2/doc/orgguide.texi')
| -rw-r--r-- | elpa/org-9.5.2/doc/orgguide.texi | 2688 |
1 files changed, 2688 insertions, 0 deletions
diff --git a/elpa/org-9.5.2/doc/orgguide.texi b/elpa/org-9.5.2/doc/orgguide.texi new file mode 100644 index 0000000..5b4a116 --- /dev/null +++ b/elpa/org-9.5.2/doc/orgguide.texi @@ -0,0 +1,2688 @@ +\input texinfo @c -*- texinfo -*- +@c %**start of header +@setfilename orgguide.info +@settitle Org Mode Compact Guide +@documentencoding UTF-8 +@documentlanguage en +@set txicodequoteundirected +@set txicodequotebacktick +@set MAINTAINERSITE @uref{https://orgmode.org,maintainers webpage} +@set MAINTAINER Bastien Guerry +@set MAINTAINEREMAIL @email{bzg@gnu.org} +@set MAINTAINERCONTACT @uref{mailto:bzg@gnu.org,contact the maintainer} +@c %**end of header + +@copying +Copyright @copyright{} 2004--2021 Free Software Foundation, Inc. + +@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.'' +in the full Org manual, which is distributed together with this +compact guide. + +(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and +modify this GNU manual.'' + +@end quotation +@end copying + +@dircategory Emacs editing modes +@direntry +* Org Guide: (orgguide). Abbreviated Org mode manual. +@end direntry + +@finalout +@titlepage +@title Org Mode Compact Guide +@subtitle Release 9.5 +@author The Org Mode Developers +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@contents + +@ifnottex +@node Top +@top Org Mode Compact Guide + +@insertcopying +@end ifnottex + +@menu +* Introduction:: Welcome! +* 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:: Storing information about an entry. +* Dates and Times:: Making items useful for planning. +* Capture, Refile, Archive: Capture Refile Archive. The ins and outs for projects. +* Agenda Views:: Collecting information into views. +* Markup:: Compose beautiful documents. +* Exporting:: Sharing and publishing notes. +* Publishing:: Create a web site of linked Org files. +* Working with Source Code:: Export, evaluate, and tangle code blocks. +* Miscellaneous:: All the rest which did not fit elsewhere. + +@detailmenu +--- The Detailed Node Listing --- + +Document Structure + +* Headlines:: How to typeset Org tree nodes. +* 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. + +TODO Items + +* TODO Basics:: Marking and displaying TODO entries. +* Multi-state Workflow:: More than just on/off. +* 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. + +Dates and Times + +* Timestamps:: Assigning a time to a tree entry. +* Creating Timestamps:: Commands that insert timestamps. +* Deadlines and Scheduling:: Planning your work. +* Clocking Work Time:: Tracking how long you spent on a task. + +Capture, Refile, Archive + +* Capture:: Capturing new stuff. +* Refile and Copy:: Moving/copying a tree from one place to another. +* Archiving:: What to do with finished products. + +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? +* Global TODO List:: All unfinished action items. +* Matching Tags and Properties:: Structured information with fine-tuned search. +* Search View:: Find entries by searching for text. +* Agenda Commands:: Remote editing of Org trees. +* Custom Agenda Views:: Defining special searches and views. + +Markup + +* Paragraphs:: The basic unit of text. +* Emphasis and Monospace:: Bold, italic, etc. +* Embedded @LaTeX{}:: LaTeX can be freely used inside Org documents. +* Literal examples:: Source code examples with special formatting. +* Images:: Display an image. +* Creating Footnotes:: Edit and read footnotes. + +Exporting + +* The Export Dispatcher:: The main interface. +* Export Settings:: Common export settings. +* Table of Contents:: The if and where of the table of contents. +* Include Files:: Include additional files into a document. +* Comment Lines:: What will not be exported. +* ASCII/UTF-8 Export:: Exporting to flat files with encoding. +* HTML Export:: Exporting to HTML. +* @LaTeX{} Export:: Exporting to @LaTeX{} and processing to PDF. +* iCalendar Export:: Exporting to iCalendar. + +@end detailmenu +@end menu + +@node Introduction +@chapter Introduction + +Org is a mode for keeping notes, maintaining TODO lists, and doing +project planning with a fast and effective plain-text system. It is +also an authoring and publishing system, and it supports working with +source code for literal programming and reproducible research. + +This document is a much compressed derivative of the @ref{Top,comprehensive Org +mode manual,,org,}. 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 pages manual because of sheer size. + +@anchor{Installation} +@heading Installation + +@quotation Important +If you are using a version of Org that is part of the Emacs +distribution, please skip this section and go directly to @ref{Activation}. + +@end quotation + +If you have downloaded Org from the web, either as a distribution +@samp{.zip} or @samp{.tar} file, or as a Git archive, it is best to run it +directly from the distribution directory. You need to add the @samp{lisp/} +subdirectories to the Emacs load path. To do this, add the following +line to your Emacs init file: + +@example +(add-to-list 'load-path "~/path/to/orgdir/lisp") +@end example + + +@noindent +If you have been using git or a tar ball to get Org, you need to run +the following command to generate autoload information. + +@example +make autoloads +@end example + +@anchor{Activation} +@heading Activation + +Add the following lines to your Emacs init file to define @emph{global} +keys for three commands that are useful in any Emacs buffer, not just +Org buffers. Please choose suitable keys yourself. + +@lisp +(global-set-key (kbd "C-c l") #'org-store-link) +(global-set-key (kbd "C-c a") #'org-agenda) +(global-set-key (kbd "C-c c") #'org-capture) +@end lisp + +Files with extension @samp{.org} will be put into Org mode automatically. + +@anchor{Feedback} +@heading 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}. For information on how to submit bug +reports, see the main manual. + +@node Document Structure +@chapter Document Structure + +Org is an outliner. Outlines allow a document to be organized in +a hierarchical structure, which, least for me, is the best +representation of notes and thoughts. An overview of this structure +is achieved by folding, i.e., 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 and hide functionalities into a single command, +@code{org-cycle}, which is bound to the @kbd{@key{TAB}} key. + +@menu +* Headlines:: How to typeset Org tree nodes. +* 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. +@end menu + +@node Headlines +@section Headlines + +Headlines define the structure of an outline tree. The headlines in +Org start 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.} with one or more stars followed by +a space. For example: + +@example +* Top level headline +** Second level +*** Third level + some text +*** Third level + more text +* Another top level headline +@end example + +Note that a headline named after @code{org-footnote-section}, which +defaults to @samp{Footnotes}, is considered as special. A subtree with +this headline will be silently ignored by exporting functions. + +Some people find the many stars too noisy and would prefer an outline +that has whitespace followed by a single star as headline starters. +See @ref{Miscellaneous} for a setup to realize this. + +@node Visibility Cycling +@section Visibility Cycling + +Outlines make it possible to hide parts of the text in the buffer. +Org uses just two commands, bound to @kbd{@key{TAB}} and +@{@{@{kbd@{S-TAB)@}@}@} to change the visibility in the buffer. + +@table @asis +@item @kbd{@key{TAB}} +@emph{Subtree cycling}: Rotate current subtree among the states + +@example +,-> FOLDED -> CHILDREN -> SUBTREE --. +'-----------------------------------' +@end example + + +When called with a prefix argument (@kbd{C-u @key{TAB}}), or with the +Shift key, global cycling is invoked. + +@item @kbd{S-@key{TAB}} +@itemx @kbd{C-u @key{TAB}} +@emph{Global cycling}: Rotate the entire buffer among the states + +@example +,-> OVERVIEW -> CONTENTS -> SHOW ALL --. +'--------------------------------------' +@end example + +@item @kbd{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 @samp{STARTUP} keyword to @samp{overview}, @samp{content}, +@samp{showall}, @samp{showeverything} or @samp{show<n>levels} (n = 2..5) like this: + +@example +#+STARTUP: content +@end example + +@node Motion +@section Motion + +The following commands jump to other headlines in the buffer. + +@table @asis +@item @kbd{C-c C-n} +Next heading. + +@item @kbd{C-c C-p} +Previous heading. + +@item @kbd{C-c C-f} +Next heading same level. + +@item @kbd{C-c C-b} +Previous heading same level. + +@item @kbd{C-c C-u} +Backward to higher level heading. +@end table + +@node Structure Editing +@section Structure Editing + +@table @asis +@item @kbd{M-@key{RET}} +Insert new heading with same level as current. If point is in +a plain list item, a new item is created (see @ref{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 @kbd{M-S-@key{RET}} +Insert new TODO entry with same level as current heading. + +@item @kbd{@key{TAB}} in new +@itemx empty entry +In a new entry with no text yet, @kbd{@key{TAB}} cycles through +reasonable levels. + +@item @kbd{M-@key{LEFT}} +@itemx @kbd{M-@key{RIGHT}} +Promote or demote current heading by one level. + +@item @kbd{M-@key{UP}} +@itemx @kbd{M-@key{DOWN}} +Move subtree up or down, i.e., swap with previous or next subtree of +same level. + +@item @kbd{C-c C-w} +Refile entry or region to a different location. See @ref{Refile and Copy}. + +@item @kbd{C-x n s} +@itemx @kbd{C-x n w} +Narrow buffer to current subtree and 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 +@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 variable @code{org-show-context-detail} to decide 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 @asis +@item @kbd{C-c /} +This prompts for an extra key to select a sparse-tree creating +command. + +@item @kbd{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}. + +The other sparse tree commands select headings based on TODO +keywords, tags, or properties and will be discussed later in this +manual. +@end table + +@node Plain Lists +@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 (see @ref{Checkboxes}). Org supports editing such lists, and +every exporter (see @ref{Exporting}) can parse and format them. + +Org knows ordered lists, unordered lists, and description lists. + +@itemize +@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. An item ends before the next line that is indented like +its bullet/number, or less. A list ends when all items are closed, or +before two blank lines. An example: + +@example +* 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: + - Elijah Wood :: He plays Frodo + - Sean Astin :: He plays Sam, Frodo's friend. +@end example + +The following commands act on items when point is in the first line of +an item (the line with the bullet or number). + +@table @asis +@item @kbd{@key{TAB}} +Items can be folded just like headline levels. + +@item @kbd{M-@key{RET}} +Insert new item at current level. With a prefix argument, force +a new heading (see @ref{Structure Editing}). + +@item @kbd{M-S-@key{RET}} +Insert a new item with a checkbox (see @ref{Checkboxes}). + +@item @kbd{M-S-@key{UP}} +@itemx @kbd{M-S-@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 @kbd{M-@key{LEFT}} +@itemx @kbd{M-@key{RIGHT}} +Decrease/increase the indentation of an item, leaving children +alone. + +@item @kbd{M-S-@key{LEFT}} +@itemx @kbd{M-S-@key{RIGHT}} +Decrease/increase the indentation of the item, including subitems. + +@item @kbd{C-c C-c} +If there is a checkbox (see @ref{Checkboxes}) in the item line, toggle +the state of the checkbox. Also verify bullets and indentation +consistency in the whole list. + +@item @kbd{C-c -} +Cycle the entire list level through the different itemize/enumerate +bullets (@samp{-}, @samp{+}, @samp{*}, @samp{1.}, @samp{1)}). +@end table + +@node Tables +@chapter Tables + +Org comes with a fast and intuitive table editor. Spreadsheet-like +calculations are supported in connection with the Emacs Calc package +(see @ref{Top,GNU Emacs Calculator Manual,,calc,}). + +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: + +@example +| Name | Phone | Age | +|-------+-------+-----| +| Peter | 1234 | 17 | +| Anna | 4321 | 25 | +@end example + +A table is re-aligned automatically each time you press @kbd{@key{TAB}} +or @kbd{@key{RET}} or @kbd{C-c C-c} inside the table. +@kbd{@key{TAB}} also moves to the next field (@kbd{@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 + +@example +|Name|Phone|Age| +|- +@end example + + +@noindent +and then press @kbd{@key{TAB}} to align the table and start filling in +fields. Even faster would be to type @samp{|Name|Phone|Age} followed by +@kbd{C-c @key{RET}}. + +When typing text into a field, Org treats @kbd{DEL}, +@kbd{Backspace}, and all character keys in a special way, so that +inserting and deleting avoids shifting other fields. Also, when +typing @emph{immediately after point was moved into a new field with +@kbd{@key{TAB}}, @kbd{S-@key{TAB}} or @kbd{@key{RET}}}, the field is +automatically made blank. + +@anchor{Creation and conversion} +@heading Creation and conversion + +@table @asis +@item @kbd{C-c |} +Convert the active region to table. If every line contains at least +one @kbd{@key{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 is easier just to start typing, like @kbd{| N a m e | P h o n e | A g e @key{RET} | - @key{TAB}}. +@end table + +@anchor{Re-aligning and field motion} +@heading Re-aligning and field motion + +@table @asis +@item @kbd{C-c C-c} +Re-align the table without moving point. + +@item @kbd{@key{TAB}} +Re-align the table, move to the next field. Creates a new row if +necessary. + +@item @kbd{S-@key{TAB}} +Re-align, move to previous field. + +@item @kbd{@key{RET}} +Re-align the table and move down to next row. Creates a new row if +necessary. + +@item @kbd{S-@key{UP}} +@itemx @kbd{S-@key{DOWN}} +@itemx @kbd{S-@key{LEFT}} +@itemx @kbd{S-@key{RIGHT}} +Move a cell up, down, left, and right by swapping with adjacent +cell. +@end table + +@anchor{Column and row editing} +@heading Column and row editing + +@table @asis +@item @kbd{M-@key{LEFT}}, @kbd{M-@key{RIGHT}} +Move the current column left/right. + +@item @kbd{M-S-@key{LEFT}} +Kill the current column. + +@item @kbd{M-S-@key{RIGHT}} +Insert a new column to the left of point position. + +@item @kbd{M-@key{UP}}, @kbd{M-@key{DOWN}} +Move the current row up/down. + +@item @kbd{M-S-@key{UP}} +Kill the current row or horizontal line. + +@item @kbd{M-S-@key{DOWN}} +Insert a new row above the current row. With a prefix argument, the +line is created below the current one. + +@item @kbd{C-c -} +Insert a horizontal line below current row. With a prefix argument, +the line is created above the current line. + +@item @kbd{C-c @key{RET}} +Insert a horizontal line below current row, and move the point into +the row below that line. + +@item @kbd{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 + +@node Hyperlinks +@chapter Hyperlinks + +Like HTML, Org provides links inside a file, external links to other +files, Usenet articles, emails, and much more. + +Org recognizes plain URIs, possibly wrapped within angle brackets, and +activate them as clickable links. The general link format, however, +looks like this: + +@example +[[LINK][DESCRIPTION]] +@end example + + +@noindent +or alternatively + +@example +[[LINK]] +@end example + + +Once a link in the buffer is complete, with all brackets present, Org +changes 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 @var{LINK} part, use @kbd{C-c C-l} +with the point on the link. + +@anchor{Internal links} +@heading 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 links to the entry with the @samp{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{<<My Target>>}. + +@anchor{External Links} +@heading 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: + +@multitable {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} +@item @samp{http://www.astro.uva.nl/=dominik} +@tab on the web +@item @samp{file:/home/dominik/images/jupiter.jpg} +@tab file, absolute path +@item @samp{/home/dominik/images/jupiter.jpg} +@tab same as above +@item @samp{file:papers/last.pdf} +@tab file, relative path +@item @samp{./papers/last.pdf} +@tab same as above +@item @samp{file:projects.org} +@tab another Org file +@item @samp{docview:papers/last.pdf::NNN} +@tab open in DocView mode at page @var{NNN} +@item @samp{id:B7423F4D-2E8A-471B-8810-C40F074717E9} +@tab link to heading by ID +@item @samp{news:comp.emacs} +@tab Usenet link +@item @samp{mailto:adent@@galaxy.net} +@tab mail link +@item @samp{mhe:folder#id} +@tab MH-E message link +@item @samp{rmail:folder#id} +@tab Rmail message link +@item @samp{gnus:group#id} +@tab Gnus article link +@item @samp{bbdb:R.*Stallman} +@tab BBDB link (with regexp) +@item @samp{irc:/irc.com/#emacs/bob} +@tab IRC link +@item @samp{info:org#Hyperlinks} +@tab Info node link +@end multitable + +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 are a few +examples,, together with an explanation: + +@multitable {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaa} +@item @samp{file:~/code/main.c::255} +@tab Find line 255 +@item @samp{file:~/xx.org::My Target} +@tab Find @samp{<<My Target>>} +@item @samp{[[file:~/xx.org::#my-custom-id]]} +@tab Find entry with a custom ID +@end multitable + +@anchor{Handling Links} +@heading 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. + +The main function is @code{org-store-link}, called with @kbd{M-x org-store-link}. Because of its importance, we suggest to bind it +to a widely available key (see @ref{Activation}). It stores a link to the +current location. The link is stored for later insertion into an Org +buffer---see below. + +From an Org buffer, the following commands create, navigate or, more +generally, act on links. + +@table @asis +@item @kbd{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 @kbd{@key{UP}} +and @kbd{@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. + +@item @kbd{C-c C-l} (with point on existing link) +When point is on an existing link, @kbd{C-c C-l} allows you to +edit the link and description parts of the link. + +@item @kbd{C-c C-o} +Open link at point. + +@item @kbd{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. +@end table + +@node TODO Items +@chapter TODO Items + +Org mode does not require TODO lists to live in separate documents. +Instead, TODO items are part of a 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 TODO items remain in the context from which they +emerged. + +Org mode provides methods to give you an overview of all the things +that you have to do, collected from many files. + +@menu +* TODO Basics:: Marking and displaying TODO entries. +* Multi-state Workflow:: More than just on/off. +* 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 TODO Basics +@section Basic TODO Functionality + +Any headline becomes a TODO item when it starts with the word @samp{TODO}, +for example: + +@example +*** TODO Write letter to Sam Fortune +@end example + + +The most important commands to work with TODO entries are: + +@table @asis +@item @kbd{C-c C-t} +Rotate the TODO state of the current item among + +@example +,-> (unmarked) -> TODO -> DONE --. +'--------------------------------' +@end example + + +The same rotation can also be done ``remotely'' from the agenda buffer +with the @kbd{t} command key (see @ref{Agenda Commands}). + +@item @kbd{S-@key{RIGHT}} +@itemx @kbd{S-@key{LEFT}} +Select the following/preceding TODO state, similar to cycling. + +@item @kbd{C-c / t} +View TODO items in a @emph{sparse tree} (see @ref{Sparse Trees}). Folds the +entire buffer, but shows all TODO items---with not-DONE state---and +the headings hierarchy above them. + +@item @kbd{M-x org-agenda t} +Show the global TODO list. Collects the TODO items (with not-DONE +states) from all agenda files (see @ref{Agenda Views}) into a single +buffer. See @ref{Global TODO List}, for more information. + +@item @kbd{S-M-@key{RET}} +Insert a new TODO entry below the current one. +@end table + +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 Workflow +@section Multi-state Workflow + +You can use TODO keywords to indicate @@emph@{sequential@} working progress +states: + +@lisp +(setq org-todo-keywords + '((sequence "TODO" "FEEDBACK" "VERIFY" "|" "DONE" "DELEGATED"))) +@end lisp + +@noindent +The vertical bar separates the @samp{TODO} keywords (states that @emph{need +action}) from the @samp{DONE} states (which need @emph{no further action}). If +you do not provide the separator bar, the last state is used as the +@samp{DONE} state. With this setup, the command @kbd{C-c C-t} cycles +an entry from @samp{TODO} to @samp{FEEDBACK}, then to @samp{VERIFY}, and finally to +@samp{DONE} and @samp{DELEGATED}. + +Sometimes you may want to use different sets of TODO keywords in +parallel. For example, you may want to have the basic @samp{TODO=/=DONE}, +but also a workflow for bug fixing. Your setup would then look like +this: + +@lisp +(setq org-todo-keywords + '((sequence "TODO(t)" "|" "DONE(d)") + (sequence "REPORT(r)" "BUG(b)" "KNOWNCAUSE(k)" "|" "FIXED(f)"))) +@end lisp + +@noindent +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. + +@example +#+TODO: TODO(t) | DONE(d) +#+TODO: REPORT(r) BUG(b) KNOWNCAUSE(k) | FIXED(f) +#+TODO: | CANCELED(c) +@end example + +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 +@section Progress Logging + +To record a timestamp and a note when changing a TODO state, call the +command @code{org-todo} with a prefix argument. + +@table @asis +@item @kbd{C-u C-c C-t} +Prompt for a note and record a the time of the TODO state change. +@end table + +Org mode can also automatically record a timestamp and optionally 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}. + +@anchor{Closing items} +@subheading Closing items + +The most basic logging is to keep track of @emph{when} a certain TODO item +was marked as done. This can be achieved with@footnote{The corresponding in-buffer setting is @samp{#+STARTUP: logdone}.} + +@lisp +(setq org-log-done 'time) +@end lisp + +@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]} is inserted just +after the headline. + +If you want to record a note along with the timestamp, use@footnote{The corresponding in-buffer setting is @samp{#+STARTUP: +logenotedone}.} + +@lisp +(setq org-log-done 'note) +@end lisp + +@noindent +You are then be prompted for a note, and that note is stored below the +entry with a @samp{Closing Note} heading. + +@anchor{Tracking TODO state changes} +@subheading 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 are 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: + +@example +#+TODO: TODO(t) WAIT(w@@/!) | DONE(d!) CANCELED(c@@) +@end example + + +@noindent +defines TODO keywords and fast access keys, and also request that +a time is recorded when the entry is set to @samp{DONE}, and that a note is +recorded when switching to @samp{WAIT} or @samp{CANCELED}. The same syntax +works also when setting @code{org-todo-keywords}. + +@node Priorities +@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 + +@example +*** TODO [#A] Write letter to Sam Fortune +@end example + + +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 @asis +@item @kbd{C-c ,} +Set the priority of the current headline. Press @kbd{A}, +@kbd{B} or @kbd{C} to select a priority, or @kbd{@key{SPC}} +to remove the cookie. + +@item @kbd{S-@key{UP}} (@code{org-priority-up}) +@itemx @kbd{S-@key{DOWN}} (@code{org-priority-down}) +Increase/decrease the priority of the current headline. +@end table + +@node Breaking Down Tasks +@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 an +overview of the fraction of subtasks that have already been marked +as done, insert either @samp{[/]} or @samp{[%]} anywhere in the headline. These +cookies are updated each time the TODO status of a child changes, or +when pressing @kbd{C-c C-c} on the cookie. For example: + +@example +* Organize Party [33%] +** TODO Call people [1/2] +*** TODO Peter +*** DONE Sarah +** TODO Buy food +** DONE Talk to neighbor +@end example + +@node Checkboxes +@section Checkboxes + +Every item in a plain list (see @ref{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. + +@example +* TODO Organize party [2/4] + - [-] call people [1/2] + - [ ] Peter + - [X] Sarah + - [X] order food +@end example + +Checkboxes work hierarchically, so if a checkbox item has children +that are checkboxes, toggling one of the children checkboxes makes the +parent checkbox reflect if none, some, or all of the children are +checked. + +The following commands work with checkboxes: + +@table @asis +@item @kbd{C-c C-c} +Toggle checkbox status or---with prefix argument---checkbox presence +at point. + +@item @kbd{M-S-@key{RET}} +Insert a new item with a checkbox. This works only if point is +already in a plain list item (see @ref{Plain Lists}). +@end table + +@node Tags +@chapter Tags + +An excellent way to implement labels and contexts for +cross-correlating information is to assign @emph{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 +by default are in bold face with the same color as the headline. + +@anchor{Tag inheritance} +@heading Tag inheritance + +Tags make use of the hierarchical structure of outline trees. If +a heading has a certain tag, all subheadings inherit the tag as well. +For example, in the list + +@example +* Meeting with the French group :work: +** Summary by Frank :boss:notes: +*** TODO Prepare slides for him :action: +@end example + +@noindent +the final heading has 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.}: + +@example +#+FILETAGS: :Peter:Boss:Secret: +@end example + +@anchor{Setting tags} +@heading 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 @asis +@item @kbd{C-c C-q} +Enter new tags for the current headline. Org mode either offers +completion or a special single-key interface for setting tags, see +below. + +@item @kbd{C-c C-c} +When point is in a headline, this does the same as @kbd{C-c C-q}. +@end table + +Org supports 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 using the @samp{TAGS} keyword, like + +@example +#+TAGS: @@work @@home @@tennisclub +#+TAGS: laptop car pc sailboat +@end example + + +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 Emacs init 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: + +@lisp +(setq org-tag-alist '(("@@work" . ?w) ("@@home" . ?h) ("laptop" . ?l))) +@end lisp + +If the tag is only relevant to the file you are working on, then you +can instead set the @samp{TAGS} keyword as: + +@example +#+TAGS: @@work(w) @@home(h) @@tennisclub(t) laptop(l) pc(p) +@end example + +@anchor{Tag groups} +@heading Tag groups + +A tag can be defined as a @emph{group tag} for a set of other tags. The +group tag can be seen as the ``broader term'' for its set of tags. + +You can set group tags by using brackets and inserting a colon between +the group tag and its related tags: + +@example +#+TAGS: [ GTD : Control Persp ] +@end example + + +@noindent +or, if tags in the group should be mutually exclusive: + +@example +#+TAGS: @{ Context : @@Home @@Work @} +@end example + + +When you search for a group tag, it return matches for all members in +the group and its subgroups. In an agenda view, filtering by a group +tag displays or hide headlines tagged with at least one of the members +of the group or any of its subgroups. + +If you want to ignore group tags temporarily, toggle group tags +support with @code{org-toggle-tags-groups}, bound to @kbd{C-c C-x q}. + +@anchor{Tag searches} +@heading Tag searches + +@table @asis +@item @kbd{C-c / m} or @kbd{C-c \} +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 @kbd{M-x org-agenda m} +Create a global list of tag matches from all agenda files. See +@ref{Matching Tags and Properties}. + +@item @kbd{M-x org-agenda M} +Create a global list of tag matches from all agenda files, but check +only TODO items and force checking subitems (see the option +@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 more detailed description +with many examples, see @ref{Matching Tags and Properties}. + +@node Properties +@chapter Properties + +Properties are key-value pairs associated with an entry. They live in +a special drawer with the name @samp{PROPERTIES}. Each property is +specified on a single line, with the key (surrounded by colons) first, +and the value after it: + +@example +* CD collection +** Classic +*** Goldberg Variations + :PROPERTIES: + :Title: Goldberg Variations + :Composer: J.S. Bach + :Publisher: Deutsche Grammophon + :NDisks: 1 + :END: +@end example + +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 applies 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 pre-define publishers and the number of +disks in a box like this: + +@example +* CD collection + :PROPERTIES: + :NDisks_ALL: 1 2 3 4 + :Publisher_ALL: "Deutsche Grammophon" Philips EMI + :END: +@end example + +If you want to set properties that can be inherited by any entry in +a file, use a line like: + +@example +#+PROPERTY: NDisks_ALL 1 2 3 4 +@end example + + +The following commands help to work with properties: + +@table @asis +@item @kbd{C-c C-x p} +Set a property. This prompts for a property name and a value. + +@item @kbd{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 (see +@ref{Tags}). The syntax for the search string is described in @ref{Matching Tags and Properties}. + +@node Dates and Times +@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 that insert timestamps. +* Deadlines and Scheduling:: Planning your work. +* Clocking Work Time:: Tracking how long you spent on a task. +@end menu + +@node Timestamps +@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 (see [BROKEN LINK: *The Weekly/daily Agenda]). We distinguish: + +@table @asis +@item 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. + +@example +* Meet Peter at the movies + <2006-11-01 Wed 19:15> +* Discussion on climate change + <2006-11-02 Thu 20:00-22:00> +@end example + +@item 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 shows up in the agenda every Wednesday: + +@example +* Pick up Sam at school + <2007-05-16 Wed 12:30 +1w> +@end example + +@item Diary-style expression entries +@cindex diary style timestamps +@cindex sexp timestamps +For more complex date specifications, Org mode supports using the +special expression diary entries implemented in the Emacs Calendar +package. For example, with optional time: + +@example +* 22:00-23:00 The nerd meeting on every 2nd Thursday of the month + <%%(diary-float t 4 2)> +@end example + +@item Time/Date range +Two timestamps connected by @samp{--} denote a range. + +@example +** Meeting in Amsterdam + <2004-08-23 Mon>--<2004-08-26 Thu> +@end example + +@item 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. + +@example +* Gillian comes late for the fifth time + [2006-11-01 Wed] +@end example +@end table + +@node Creating Timestamps +@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 @asis +@item @kbd{C-c .} +Prompt for a date and insert a corresponding timestamp. When point +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 argument, it also adds the current time. + +@item @kbd{C-c !} +Like @kbd{C-c .}, but insert an inactive timestamp that does +not cause an agenda entry. + +@item @kbd{S-@key{LEFT}} +@itemx @kbd{S-@key{RIGHT}} +Change date at point by one day. + +@item @kbd{S-@key{UP}} +@itemx @kbd{S-@key{DOWN}} +On the beginning or enclosing bracket of a timestamp, change its +type. Within a timestamp, change the item under point. Point 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 +also shifts 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 accepts any string +containing some date and/or time information, and intelligently +interprets 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 +@section Deadlines and Scheduling + +A timestamp may be preceded by special keywords to facilitate +planning: + +@table @asis +@item @kbd{C-c C-d} +Insert @samp{DEADLINE} keyword along with a time stamp, in the line +following the headline. + +Meaning: the task---most likely a TODO item, though not +necessarily---is supposed to be finished on that date. + +On the deadline date, the task is listed in the agenda. In +addition, the agenda for @emph{today} carries 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 as +done. An example: + +@example +*** TODO write article about the Earth for the Guide + DEADLINE: <2004-02-29 Sun> + The editor in charge is [[bbdb:Ford Prefect]] +@end example + +@item @kbd{C-c C-s} +Insert @samp{SCHEDULED} keyword along with a stamp, in the line following +the headline. + +Meaning: you are planning to start working on that task on the given +date@footnote{This is quite different from what is normally understood by +@emph{scheduling a meeting}, which is done in Org by just inserting a time +stamp without keyword.}. + +The headline is listed under the given date@footnote{It will still be listed on that date after it has been marked +as done. If you do not like this, set the variable +@code{org-agenda-skip-scheduled-if-done}.}. In addition, +a reminder that the scheduled date has passed is present in the +compilation for @emph{today}, until the entry is marked as done, i.e., +the task is automatically forwarded until completed. + +@example +*** TODO Call Trillian for a date on New Years Eve. + SCHEDULED: <2004-12-25 Sat> +@end example +@end table + +Some tasks need to be repeated again and again. Org mode helps to +organize such tasks using a so-called repeater in a @samp{DEADLINE}, +@samp{SCHEDULED}, or plain timestamps. In the following example: + +@example +** TODO Pay the rent + DEADLINE: <2005-10-01 Sat +1m> +@end example + +@noindent +the @samp{+1m} is a repeater; the intended interpretation is that the task +has a deadline on @samp{<2005-10-01>} and repeats itself every (one) month +starting from that time. + +@node Clocking Work Time +@section Clocking Work Time + +Org mode allows you to clock the time you spend on specific tasks in +a project. + +@table @asis +@item @kbd{C-c C-x C-i} +Start the clock on the current item (clock-in). This inserts the +@samp{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. + +@item @kbd{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 @kbd{C-c C-x C-e} +Update the effort estimate for the current clock task. + +@item @kbd{C-c C-x C-q} +Cancel the current clock. This is useful if a clock was started by +mistake, or if you ended up working on something else. + +@item @kbd{C-c C-x C-j} +Jump to the headline of the currently clocked in task. With +a @kbd{C-u} prefix argument, select the target task from a list +of recently clocked tasks. +@end table + +The @kbd{l} key may be used in the agenda (see [BROKEN LINK: *The Weekly/daily Agenda]) to show which tasks have been worked on or closed during +a day. + +@node Capture Refile Archive +@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 does this using a process called @emph{capture}. It also can +store files related to a task (@emph{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 +* Capture:: Capturing new stuff. +* Refile and Copy:: Moving/copying a tree from one place to another. +* Archiving:: What to do with finished products. +@end menu + +@node Capture +@section Capture + +Capture lets you quickly store notes with little interruption of your +work flow. You can define templates for new entries and associate +them with different targets for storing notes. + +@anchor{Setting up capture} +@subheading Setting up capture + +The following customization sets a default target@footnote{Using capture templates, you get finer control over capture +locations. See @ref{Capture templates}.} file for notes. + +@lisp +(setq org-default-notes-file (concat org-directory "/notes.org")) +@end lisp + +You may also define a global key for capturing new material (see +@ref{Activation}). + +@anchor{Using capture} +@subheading Using capture + +@table @asis +@item @kbd{M-x org-capture} +Start a capture process, placing you into a narrowed indirect buffer +to edit. + +@item @kbd{C-c C-c} +Once you have finished entering information into the capture buffer, +@kbd{C-c C-c} returns you to the window configuration before +the capture process, so that you can resume your work without +further distraction. + +@item @kbd{C-c C-w} +Finalize the capture process by refiling the note to a different +place (see @ref{Refile and Copy}). + +@item @kbd{C-c C-k} +Abort the capture process and return to the previous state. +@end table + +@anchor{Capture templates} +@subheading Capture templates + +You can use templates for different types of capture items, and for +different target locations. Say you would like to use one template to +create general TODO entries, and you want to put these entries under +the heading @samp{Tasks} in your file @samp{~/org/gtd.org}. Also, a date tree +in the file @samp{journal.org} should capture journal entries. A possible +configuration would look like: + +@lisp +(setq org-capture-templates + '(("t" "Todo" entry (file+headline "~/org/gtd.org" "Tasks") + "* TODO %?\n %i\n %a") + ("j" "Journal" entry (file+datetree "~/org/journal.org") + "* %?\nEntered on %U\n %i\n %a"))) +@end lisp + +If you then press @kbd{t} from the capture menu, Org will prepare +the template for you like this: + +@example +* TODO + [[file:LINK TO WHERE YOU INITIATED CAPTURE]] +@end example + + +@noindent +During expansion of the template, special %-escapes@footnote{If you need one of these sequences literally, escape the @samp{%} +with a backslash.} allow +dynamic insertion of content. Here is a small selection of the +possibilities, consult the manual for more. + +@multitable {aaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} +@item @samp{%a} +@tab annotation, normally the link created with @code{org-store-link} +@item @samp{%i} +@tab initial content, the region when capture is called with @kbd{C-u} +@item @samp{%t}, @samp{%T} +@tab timestamp, date only, or date and time +@item @samp{%u}, @samp{%U} +@tab like above, but inactive timestamps +@item @samp{%?} +@tab after completing the template, position point here +@end multitable + +@node Refile and Copy +@section Refile and Copy + +When reviewing the captured data, you may want to refile or to copy +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 @asis +@item @kbd{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 @kbd{C-u C-c C-w} +Use the refile interface to jump to a heading. + +@item @kbd{C-u C-u C-c C-w} +Jump to the location where @code{org-refile} last moved a tree to. + +@item @kbd{C-c M-w} +Copying works like refiling, except that the original note is not +deleted. +@end table + +@node Archiving +@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 @asis +@item @kbd{C-c C-x C-a} +Archive the current entry using the command specified in the +variable @code{org-archive-default-command}. + +@item @kbd{C-c C-x C-s} or short @kbd{C-c $} +Archive the subtree starting at point 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 @samp{_archive} to the +current file name. You can also choose what heading to file archived +items under, with the possibility to add them to a datetree in a file. +For information and examples on how to specify the file and the +heading, see the documentation string of the variable +@code{org-archive-location}. + +There is also an in-buffer option for setting this variable, for +example: + +@example +#+ARCHIVE: %s_done:: +@end example + +@node Agenda Views +@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. + +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. For commands available in the +Agenda buffer, see @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? +* Global TODO List:: All unfinished action items. +* Matching Tags and Properties:: Structured information with fine-tuned search. +* Search View:: Find entries by searching for text. +* Agenda Commands:: Remote editing of Org trees. +* Custom Agenda Views:: Defining special searches and views. +@end menu + +@node Agenda Files +@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 @asis +@item @kbd{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 @kbd{C-c ]} +Remove current file from the list of agenda files. + +@item @kbd{C-'} +@itemx @kbd{C-,} +Cycle through agenda file list, visiting one file after the other. +@end table + +@node Agenda Dispatcher +@section The Agenda Dispatcher + +The views are created through a dispatcher, accessible with @kbd{M-x org-agenda}, or, better, bound to a global key (see @ref{Activation}). +It displays a menu from which an additional letter is required to +execute a command. The dispatcher offers the following default +commands: + +@table @asis +@item @kbd{a} +Create the calendar-like agenda (see [BROKEN LINK: *The Weekly/daily Agenda]). + +@item @kbd{t} +@itemx @kbd{T} +Create a list of all TODO items (see @ref{Global TODO List}). + +@item @kbd{m} +@itemx @kbd{M} +Create a list of headlines matching a given expression (see +@ref{Matching Tags and Properties}). + +@item @kbd{s} +@kindex s @r{(Agenda dispatcher)} +Create 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 +@section 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 @asis +@item @kbd{M-x org-agenda a} +Compile an agenda for the current week from a list of Org files. +The agenda shows the entries for each day. +@end table + +Org mode understands the syntax of the diary and allows you to use +diary expression entries directly in Org files: + +@example +* Holidays + :PROPERTIES: + :CATEGORY: Holiday + :END: +%%(org-calendar-holiday) ; special function for holiday names + +* Birthdays + :PROPERTIES: + :CATEGORY: Ann + :END: +%%(org-anniversary 1956 5 14) Arthur Dent is %d years old +%%(org-anniversary 1869 10 2) Mahatma Gandhi would be %d years old +@end example + +Org can interact with Emacs appointments notification facility. To +add the appointments of your agenda files, use the command +@code{org-agenda-to-appt}. + +@node Global TODO List +@section 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. For +commands available in the TODO list, see @ref{Agenda Commands}. + +@table @asis +@item @kbd{M-x org-agenda t} +Show the global TODO list. This collects the TODO items from all +agenda files (see @ref{Agenda Views}) into a single buffer. + +@item @kbd{M-x org-agenda T} +Like the above, but allows selection of a specific TODO keyword. +@end table + +@node Matching Tags and Properties +@section Matching Tags and Properties + +If headlines in the agenda files are marked with @emph{tags} (see @ref{Tags}), +or have properties (see @ref{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}. + +@table @asis +@item @kbd{M-x org-agenda 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} +(see @ref{Tags}). If you often need a specific search, define a custom +command for it (see @ref{Agenda Dispatcher}). + +@item @kbd{M-x org-agenda M} +Like @kbd{m}, but only select headlines that are also TODO +items. +@end table + +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 @samp{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 @asis +@item @samp{+work-boss} +Select headlines tagged @samp{work}, but discard those also tagged +@samp{boss}. + +@item @samp{work|laptop} +Selects lines tagged @samp{work} or @samp{laptop}. + +@item @samp{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 Search View +@section Search View + +This agenda view is a general text search facility for Org mode +entries. It is particularly useful to find notes. + +@table @asis +@item @kbd{M-x org-agenda s} (@code{org-search-view}) +@kindex s @r{(Agenda dispatcher)} +@findex org-search-view +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} matches 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]@}} matches note entries that contain the +keywords @samp{computer} and @samp{wifi}, but not the keyword @samp{ethernet}, and +which are also not matched by the regular expression @samp{8\.11[bg]}, +meaning to exclude both @samp{8.11b} and @samp{8.11g}. + +Note that in addition to the agenda files, this command also searches +the files listed in @code{org-agenda-text-search-extra-files}. + +@node Agenda Commands +@section Commands in the Agenda Buffer + +Entries in the agenda buffer are linked back to the Org file or diary +file where they originate. You are not allowed to edit the agenda +buffer itself, but 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 agenda menu and the manual for a complete list. + +@anchor{Motion (1)} +@subheading Motion + +@table @asis +@item @kbd{n} +Next line (same as @kbd{@key{DOWN}} and @kbd{C-n}). + +@item @kbd{p} +Previous line (same as @kbd{@key{UP}} and @kbd{C-p}). +@end table + +@anchor{View/Go to Org file} +@subheading View/Go to Org file + +@table @asis +@item @kbd{@key{SPC}} +Display the original location of the item in another window. +With a prefix argument, make sure that drawers stay folded. + +@item @kbd{@key{TAB}} +Go to the original location of the item in another window. + +@item @kbd{@key{RET}} +Go to the original location of the item and delete other windows. +@end table + +@anchor{Change display} +@subheading Change display + +@table @asis +@item @kbd{o} +Delete other windows. + +@item @kbd{v d} or short @kbd{d} +Switch to day view. + +@item @kbd{v w} or short @kbd{w} +Switch to week view. + +@item @kbd{f} +Go forward in time to display the span following the current one. +For example, if the display covers a week, switch to the following +week. + +@item @kbd{b} +Go backward in time to display earlier dates. + +@item @kbd{.} +Go to today. + +@item @kbd{j} +Prompt for a date and go there. + +@item @kbd{v l} or @kbd{v L} or short @kbd{l} +Toggle Logbook mode. In Logbook mode, entries that were marked as +done while logging was on (see the 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 argument, show all +possible logbook entries, including state changes. + +@item @kbd{r} +@itemx @kbd{g} +Recreate the agenda buffer, for example to reflect the changes after +modification of the timestamps of items. + +@item @kbd{s} +@kindex C-x C-s +@findex org-save-all-org-buffers +@kindex s +Save all Org buffers in the current Emacs session, and also the +locations of IDs. +@end table + +@anchor{Remote editing} +@subheading Remote editing + +@table @asis +@item @kbd{0--9} +Digit argument. + +@item @kbd{t} +Change the TODO state of the item, both in the agenda and in the +original Org file. + +@item @kbd{C-k} +Delete the current agenda item along with the entire subtree +belonging to it in the original Org file. + +@item @kbd{C-c C-w} +Refile the entry at point. + +@item @kbd{a} +Archive the subtree corresponding to the entry at point using the +default archiving command set in @code{org-archive-default-command}. + +@item @kbd{$} +Archive the subtree corresponding to the current headline. + +@item @kbd{C-c C-s} +Schedule this item. With a prefix argument, remove the +scheduling timestamp + +@item @kbd{C-c C-d} +Set a deadline for this item. With a prefix argument, remove the +deadline. + +@item @kbd{S-@key{RIGHT}} +Change the timestamp associated with the current line by one day +into the future. + +@item @kbd{S-@key{LEFT}} +Change the timestamp associated with the current line by one day +into the past. + +@item @kbd{I} +Start the clock on the current item. + +@item @kbd{O} +Stop the previously started clock. + +@item @kbd{X} +Cancel the currently running clock. + +@item @kbd{J} +Jump to the running clock in another window. +@end table + +@anchor{Quit and exit} +@subheading Quit and exit + +@table @asis +@item @kbd{q} +Quit agenda, remove the agenda buffer. + +@item @kbd{x} +Exit agenda, remove the agenda buffer and all buffers loaded by +Emacs for the compilation of the agenda. +@end table + +@node Custom Agenda Views +@section Custom Agenda Views + +The first 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} from the agenda dispatcher (see @ref{Agenda Dispatcher}). You can also directly set it with Emacs Lisp in +the Emacs init file. The following example contains all valid agenda +views: + +@lisp +(setq org-agenda-custom-commands + '(("w" todo "WAITING") + ("u" tags "+boss-urgent") + ("v" tags-todo "+boss-urgent"))) +@end lisp + +The initial string in each entry defines the keys you have to press +after the dispatcher command in order to access the command. Usually +this is 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 @asis +@item @kbd{w} +as a global search for TODO entries with @samp{WAITING} as the TODO +keyword. + +@item @kbd{u} +as a global tags search for headlines tagged @samp{boss} but not +@samp{urgent}. + +@item @kbd{v} +The same search, but limiting it to headlines that are also TODO +items. +@end table + +@node Markup +@chapter Markup for Rich Contents + +Org is primarily about organizing and searching through your +plain-text notes. However, it also provides a lightweight yet robust +markup language for rich text formatting and more. Used in +conjunction with the export framework (see @ref{Exporting}), you can author +beautiful documents in Org. + +@menu +* Paragraphs:: The basic unit of text. +* Emphasis and Monospace:: Bold, italic, etc. +* Embedded @LaTeX{}:: LaTeX can be freely used inside Org documents. +* Literal examples:: Source code examples with special formatting. +* Images:: Display an image. +* Creating Footnotes:: Edit and read footnotes. +@end menu + +@node Paragraphs +@section Paragraphs + +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 preserve the line breaks, indentation and blank lines in a region, +but otherwise use normal formatting, you can use this construct, which +can also be used to format poetry. + +@example +#+BEGIN_VERSE + Great clouds overhead + Tiny black birds rise and fall + Snow covers Emacs + + ---AlexSchroeder +#+END_VERSE +@end example + +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 documents like this: + +@example +#+BEGIN_QUOTE +Everything should be made as simple as possible, +but not any simpler ---Albert Einstein +#+END_QUOTE +@end example + +If you would like to center some text, do it like this: + +@example +#+BEGIN_CENTER +Everything should be made as simple as possible, \\ +but not any simpler +#+END_CENTER +@end example + +@node Emphasis and Monospace +@section Emphasis and Monospace + +You can make words @samp{*bold*}, @samp{/italic/}, @samp{_underlined_}, @samp{=verbatim=} +and @samp{~code~}, and, if you must, @samp{+strike-through+}. Text in the code +and verbatim string is not processed for Org specific syntax; it is +exported verbatim. + +@node Embedded @LaTeX{} +@section Embedded @LaTeX{} + +For scientific notes which need to be able to contain mathematical +symbols and the occasional formula, Org mode supports embedding @LaTeX{} +code into its files. You can directly use @TeX{}-like syntax for special +symbols, enter formulas and entire @LaTeX{} environments. + +@example +The radius of the sun is R_sun = 6.96 x 10^8 m. On the other hand, +the radius of Alpha Centauri is R_@{Alpha Centauri@} = 1.28 x R_@{sun@}. + +\begin@{equation@} % arbitrary environments, +x=\sqrt@{b@} % even tables, figures +\end@{equation@} % etc + +If $a^2=b$ and \( b=2 \), then the solution must be +either $$ a=+\sqrt@{2@} $$ or \[ a=-\sqrt@{2@} \]. +@end example + +@node Literal examples +@section Literal examples + +You can include literal examples that should not be subjected to +markup. Such examples are typeset in monospace, so this is well +suited for source code and similar examples. + +@example +#+BEGIN_EXAMPLE + Some example from a text file. +#+END_EXAMPLE +@end example + +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: + +@example +Here is an example + : Some example from a text file. +@end example + +If the example is source code from a programming language, or any +other text that can be marked up by Font Lock in Emacs, you can ask +for the example to look like the fontified Emacs buffer. + +@example +#+BEGIN_SRC emacs-lisp + (defun org-xor (a b) + "Exclusive or." + (if a (not b) b)) + #+END_SRC +@end example + +To edit the example in a special buffer supporting this language, use +@kbd{C-c '} to both enter and leave the editing buffer. + +@node Images +@section Images + +An image is a link to an image file that does not have a description +part, for example + +@example +./img/cat.jpg +@end example + + +If you wish to define a caption for the image and maybe a label for +internal cross references (see @ref{Hyperlinks}), make sure that the +link is on a line by itself and precede it with @samp{CAPTION} and @samp{NAME} +keywords as follows: + +@example +#+CAPTION: This is the caption for the next figure link (or table) +#+NAME: fig:SED-HR4049 +[[./img/a.jpg]] +@end example + +@node Creating Footnotes +@section Creating 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: + +@example +The Org homepage[fn:1] now looks a lot better than it used to. +... +[fn:1] The link is: https://orgmode.org +@end example + +The following commands handle footnotes: + +@table @asis +@item @kbd{C-c C-x f} +The footnote action command. When point 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 @kbd{C-c C-c} +Jump between definition and reference. +@end table + +@node Exporting +@chapter Exporting + +Org can convert and export documents to a variety of other formats +while retaining as much structure (see @ref{Document Structure}) and markup +(see @ref{Markup}) as possible. + +@menu +* The Export Dispatcher:: The main interface. +* Export Settings:: Common export settings. +* Table of Contents:: The if and where of the table of contents. +* Include Files:: Include additional files into a document. +* Comment Lines:: What will not be exported. +* ASCII/UTF-8 Export:: Exporting to flat files with encoding. +* HTML Export:: Exporting to HTML. +* @LaTeX{} Export:: Exporting to @LaTeX{} and processing to PDF. +* iCalendar Export:: Exporting to iCalendar. +@end menu + +@node The Export Dispatcher +@section The Export Dispatcher + +The export dispatcher is the main interface for Org's exports. +A hierarchical menu presents the currently configured export formats. +Options are shown as easy toggle switches on the same screen. + +@table @asis +@item @kbd{C-c C-e} +Invokes the export dispatcher interface. +@end table + +Org exports the entire buffer by default. If the Org buffer has an +active region, then Org exports just that region. + +@node Export Settings +@section Export Settings + +The exporter recognizes special lines in the buffer which provide +additional information. These lines may be put anywhere in the file: + +@example +#+TITLE: I'm in the Mood for Org +@end example + + +Most proeminent export options include: + +@multitable {aaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} +@item @samp{TITLE} +@tab the title to be shown +@item @samp{AUTHOR} +@tab the author (default taken from @code{user-full-name}) +@item @samp{DATE} +@tab a date, fixed, or an Org timestamp +@item @samp{EMAIL} +@tab email address (default from @code{user-mail-address}) +@item @samp{LANGUAGE} +@tab language code, e.g., @samp{en} +@end multitable + +Option keyword sets can be inserted from the export dispatcher (see +@ref{The Export Dispatcher}) using the @samp{Insert template} command by +pressing @kbd{#}. + +@node Table of Contents +@section Table of Contents + +The table of contents includes all headlines in the document. Its +depth is therefore the same as the headline levels in the file. If +you need to use a different depth, or turn it off entirely, set the +@code{org-export-with-toc} variable accordingly. You can achieve the same +on a per file basis, using the following @samp{toc} item in @samp{OPTIONS} +keyword: + +@example +#+OPTIONS: toc:2 (only include two levels in TOC) +#+OPTIONS: toc:nil (no default TOC at all) +@end example + +Org normally inserts the table of contents directly before the first +headline of the file. + +@node Include Files +@section Include Files + +During export, you can include the content of another file. For +example, to include your @samp{.emacs} file, you could use: + +@example +#+INCLUDE: "~/.emacs" src emacs-lisp +@end example + + +@noindent +The first parameter is the file name to include. The optional second +parameter specifies the block type: @samp{example}, @samp{export} or @samp{src}. The +optional third parameter specifies the source code language to use for +formatting the contents. This is relevant to both @samp{export} and @samp{src} +block types. + +You can visit the included file with @kbd{C-c '}. + +@node Comment Lines +@section Comment Lines + +Lines starting with zero or more whitespace characters followed by one +@samp{#} and a whitespace are treated as comments and, as such, are not +exported. + +Likewise, regions surrounded by @samp{#+BEGIN_COMMENT} @dots{} @samp{#+END_COMMENT} +are not exported. + +Finally, a @samp{COMMENT} keyword at the beginning of an entry, but after +any other keyword or priority cookie, comments out the entire subtree. +The command below helps changing the comment status of a headline. + +@table @asis +@item @kbd{C-c ;} +Toggle the @samp{COMMENT} keyword at the beginning of an entry. +@end table + +@node ASCII/UTF-8 Export +@section ASCII/UTF-8 Export + +ASCII export produces an output file containing only plain ASCII +characters. This is the simplest and most direct text output. It +does not contain any Org markup. UTF-8 export uses additional +characters and symbols available in this encoding standards. + +@table @asis +@item @kbd{C-c C-e t a} +@itemx @kbd{C-c C-e t u} +Export as an ASCII file with a @samp{.txt} extension. For @samp{myfile.org}, +Org exports to @samp{myfile.txt}, overwriting without warning. For +@samp{myfile.txt}, Org exports to @samp{myfile.txt.txt} in order to prevent +data loss. +@end table + +@node HTML Export +@section HTML Export + +Org mode contains an HTML exporter with extensive HTML formatting +compatible with XHTML 1.0 strict standard. + +@table @asis +@item @kbd{C-c C-e h h} +Export as HTML file with a @samp{.html} extension. For @samp{myfile.org}, Org +exports to @samp{myfile.html}, overwriting without warning. @kbd{C-c C-e h o} exports to HTML and opens it in a web browser. +@end table + +The HTML export back-end transforms @samp{<} and @samp{>} to @samp{<} and @samp{>}. +To include raw HTML code in the Org file so the HTML export back-end +can insert that HTML code in the output, use this inline syntax: +@samp{@@@@html:...@@@@}. For example: + +@example +@@@@html:<b>@@@@bold text@@@@html:</b>@@@@ +@end example + + +For larger raw HTML code blocks, use these HTML export code blocks: + +@example +#+HTML: Literal HTML code for export + +#+BEGIN_EXPORT html + All lines between these markers are exported literally +#+END_EXPORT +@end example + +@node @LaTeX{} Export +@section @LaTeX{} Export + +The @LaTeX{} export back-end can handle complex documents, incorporate +standard or custom @LaTeX{} document classes, generate documents using +alternate @LaTeX{} engines, and produce fully linked PDF files with +indexes, bibliographies, and tables of contents, destined for +interactive online viewing or high-quality print publication. + +By default, the @LaTeX{} output uses the @emph{article} class. You can change +this by adding an option like @samp{#+LATEX_CLASS: myclass} in your file. +The class must be listed in @code{org-latex-classes}. + +@table @asis +@item @kbd{C-c C-e l l} +Export to a @LaTeX{} file with a @samp{.tex} extension. For @samp{myfile.org}, +Org exports to @samp{myfile.tex}, overwriting without warning. + +@item @kbd{C-c C-e l p} +Export as @LaTeX{} file and convert it to PDF file. + +@item @kbd{C-c C-e l o} +Export as @LaTeX{} file and convert it to PDF, then open the PDF using +the default viewer. +@end table + +The @LaTeX{} export back-end can insert any arbitrary @LaTeX{} code, see +@ref{Embedded @LaTeX{}}. There are three ways to embed such code in the Org +file and they all use different quoting syntax. + +Inserting in-line quoted with @@ symbols: + +@example +Code embedded in-line @@@@latex:any arbitrary LaTeX code@@@@ in a paragraph. +@end example + + +Inserting as one or more keyword lines in the Org file: + +@example +#+LATEX: any arbitrary LaTeX code +@end example + + +Inserting as an export block in the Org file, where the back-end +exports any code between begin and end markers: + +@example +#+BEGIN_EXPORT latex + any arbitrary LaTeX code +#+END_EXPORT +@end example + +@node iCalendar Export +@section iCalendar Export + +A large part of Org mode's interoperability success is its ability to +easily export to or import from external applications. The iCalendar +export back-end takes calendar data from Org files and exports to the +standard iCalendar format. + +@table @asis +@item @kbd{C-c C-e c f} +Create iCalendar entries from the current Org buffer and store them +in the same directory, using a file extension @samp{.ics}. + +@item @kbd{C-c C-e c c} +Create a combined iCalendar file from Org files in +@code{org-agenda-files} and write it to +@code{org-icalendar-combined-agenda-file} file name. +@end table + +@node Publishing +@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. + +You can also use Org to convert files into PDF, or even combine HTML +and PDF conversion so that files are available in both formats on the +server. + +For detailed instructions about setup, see the manual. Here is an +example: + +@lisp +(setq org-publish-project-alist + '(("org" + :base-directory "~/org/" + :publishing-function org-html-publish-to-html + :publishing-directory "~/public_html" + :section-numbers nil + :with-toc nil + :html-head "<link rel=\"stylesheet\" + href=\"../other/mystyle.css\" + type=\"text/css\"/>"))) +@end lisp + +@table @asis +@item @kbd{C-c C-e P x} +Prompt for a specific project and publish all files that belong to +it. + +@item @kbd{C-c C-e P p} +Publish the project containing the current file. + +@item @kbd{C-c C-e P f} +Publish only the current file. + +@item @kbd{C-c C-e P a} +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. + +@node Working with Source Code +@chapter Working with Source Code + +Org mode provides a number of features for working with source code, +including editing of code blocks in their native major mode, +evaluation of code blocks, tangling of code blocks, and exporting code +blocks and their results in several formats. + +A source code block conforms to this structure: + +@example +#+NAME: <name> +#+BEGIN_SRC <language> <switches> <header arguments> + <body> +#+END_SRC +@end example + +@noindent +where: + +@itemize +@item +@samp{<name>} is a string used to uniquely name the code block, + +@item +@samp{<language>} specifies the language of the code block, e.g., +@samp{emacs-lisp}, @samp{shell}, @samp{R}, @samp{python}, etc., + +@item +@samp{<switches>} can be used to control export of the code block, + +@item +@samp{<header arguments>} can be used to control many aspects of code +block behavior as demonstrated below, + +@item +@samp{<body>} contains the actual source code. +@end itemize + +Use @kbd{C-c '} to edit the current code block. It opens a new +major mode edit buffer containing the body of the source code block, +ready for any edits. Use @kbd{C-c '} again to close the buffer +and return to the Org buffer. + +@anchor{Using header arguments} +@heading Using header arguments + +A header argument is specified with an initial colon followed by the +argument's name in lowercase. + +Header arguments can be set in several ways; Org prioritizes them in +case of overlaps or conflicts by giving local settings a higher +priority. + +@table @asis +@item System-wide header arguments +Those are specified by customizing @code{org-babel-default-header-args} +variable, or, for a specific language @var{LANG} +@code{org-babel-default-header-args:LANG}. + +@item Header arguments in properties +You can set them using @samp{header-args} property (see @ref{Properties})---or +@samp{header-args:LANG} for language @var{LANG}. Header arguments +set through properties drawers apply at the sub-tree level on down. + +@item Header arguments in code blocks +Header arguments are most commonly set at the source code block +level, on the @samp{BEGIN_SRC} line: + +@example +#+NAME: factorial +#+BEGIN_SRC haskell :results silent :exports code :var n=0 + fac 0 = 1 + fac n = n * fac (n-1) +#+END_SRC +@end example + +Code block header arguments can span multiple lines using @samp{HEADER} +keyword on each line. +@end table + +@anchor{Evaluating code blocks} +@heading Evaluating code blocks + +Use @kbd{C-c C-c} to evaluate the current code block and insert +its results in the Org document. By default, evaluation is only +turned on for @samp{emacs-lisp} code blocks, however support exists for +evaluating blocks in many languages. For a complete list of supported +languages see the manual. The following shows a code block and its +results. + +@example +#+BEGIN_SRC emacs-lisp + (+ 1 2 3 4) +#+END_SRC + +#+RESULTS: +: 10 +@end example + +The following syntax is used to pass arguments to code blocks using +the @samp{var} header argument. + +@example +:var NAME=ASSIGN +@end example + + +@noindent +@var{NAME} is the name of the variable bound in the code block +body. @var{ASSIGN} is a literal value, such as a string, +a number, a reference to a table, a list, a literal example, another +code block---with or without arguments---or the results of evaluating +a code block. + +@anchor{Results of evaluation} +@heading Results of evaluation + +How Org handles results of a code block execution depends on many +header arguments working together. The primary determinant, however, +is the @samp{results} header argument. It controls the @emph{collection}, +@emph{type}, @emph{format}, and @emph{handling} of code block results. + +@table @asis +@item Collection +How the results should be collected from the code block. You may +choose either @samp{output} or @samp{value} (the default). + +@item Type +What result types to expect from the execution of the code block. +You may choose among @samp{table}, @samp{list}, @samp{scalar}, and @samp{file}. Org +tries to guess it if you do not provide it. + +@item Format +How Org processes results. Some possible values are @samp{code}, +@samp{drawer}, @samp{html}, @samp{latex}, @samp{link}, and @samp{raw}. + +@item Handling +How to insert the results once properly formatted. Allowed values +are @samp{silent}, @samp{replace} (the default), @samp{append}, or @samp{prepend}. +@end table + +Code blocks which output results to files---e.g.: graphs, diagrams and +figures---can accept a @samp{:file FILENAME} header argument, in which case +the results are saved to the named file, and a link to the file is +inserted into the buffer. + +@anchor{Exporting code blocks} +@heading Exporting code blocks + +It is possible to export the @emph{code} of code blocks, the @emph{results} of +code block evaluation, @emph{both} the code and the results of code block +evaluation, or @emph{none}. Org defaults to exporting @emph{code} for most +languages. + +The @samp{exports} header argument is to specify if that part of the Org +file is exported to, say, HTML or @LaTeX{} formats. It can be set to +either @samp{code}, @samp{results}, @samp{both} or @samp{none}. + +@anchor{Extracting source code} +@heading Extracting source code + +Use @kbd{C-c C-v t} to create pure source code files by +extracting code from source blocks in the current buffer. This is +referred to as ``tangling''---a term adopted from the literate +programming community. During tangling of code blocks their bodies +are expanded using @code{org-babel-expand-src-block}, which can expand both +variable and ``Noweb'' style references. In order to tangle a code +block it must have a @samp{tangle} header argument, see the manual for +details. + +@node Miscellaneous +@chapter Miscellaneous + + + +@anchor{Completion} +@heading Completion + +Org has in-buffer completions with @kbd{M-@key{TAB}}. No minibuffer is +involved. Type one or more letters and invoke the hot key to complete +the text in-place. + +For example, this command will complete @TeX{} symbols after @samp{\}, TODO +keywords at the beginning of a headline, and tags after @samp{:} in +a headline. + +@anchor{Structure Templates} +@heading Structure Templates + +To quickly insert empty structural blocks, such as @samp{#+BEGIN_SRC} +@dots{} @samp{#+END_SRC}, or to wrap existing text in such a block, use + +@table @asis +@item @kbd{C-c C-,} +Prompt for a type of block structure, and insert the block at point. +If the region is active, it is wrapped in the block. +@end table + +@anchor{Clean view} +@heading Clean view + +Org's default outline with stars and no indents can become too +cluttered for short documents. For @emph{book-like} long documents, the +effect is not as noticeable. Org provides an alternate stars and +indentation scheme, as shown on the right in the following table. It +uses only one star and indents text to line with the heading: + +@example +* Top level headline | * Top level headline +** Second level | * Second level +*** Third level | * Third level + some text | some text +*** Third level | * Third level + more text | more text +* Another top level headline | * Another top level headline +@end example + +This kind of view can be achieved dynamically at display time using +Org Indent mode (@kbd{M-x org-indent-mode @key{RET}}), which prepends +intangible space to each line. You can turn on Org Indent mode for +all files by customizing the variable @code{org-startup-indented}, or you +can turn it on for individual files using + +@example +#+STARTUP: indent +@end example + + +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 @kbd{@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 + +@example +#+STARTUP: hidestars odd +@end example + +@bye
\ No newline at end of file |