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, 0 insertions, 2688 deletions
diff --git a/elpa/org-9.5.2/doc/orgguide.texi b/elpa/org-9.5.2/doc/orgguide.texi deleted file mode 100644 index 5b4a116..0000000 --- a/elpa/org-9.5.2/doc/orgguide.texi +++ /dev/null @@ -1,2688 +0,0 @@ -\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 |