diff options
Diffstat (limited to 'elpa/org-9.5.2/doc/org-guide.org')
| -rw-r--r-- | elpa/org-9.5.2/doc/org-guide.org | 2654 |
1 files changed, 2654 insertions, 0 deletions
diff --git a/elpa/org-9.5.2/doc/org-guide.org b/elpa/org-9.5.2/doc/org-guide.org new file mode 100644 index 0000000..aa793f1 --- /dev/null +++ b/elpa/org-9.5.2/doc/org-guide.org @@ -0,0 +1,2654 @@ +#+title: Org Mode Compact Guide +#+subtitle: Release {{{version}}} +#+author: The Org Mode Developers +#+language: en + +#+texinfo: @insertcopying + +* Copying +:PROPERTIES: +:copying: t +:END: + +Copyright \copy 2004--2021 Free Software Foundation, Inc. + +#+begin_quote +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_quote + +* Introduction +:PROPERTIES: +:DESCRIPTION: Welcome! +:END: + +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 [[info:org][comprehensive Org +mode manual]]. It contains all basic features and commands, along with +important hints for customization. It is intended for beginners who +would shy back from a 200 pages manual because of sheer size. + +** Installation +:PROPERTIES: +:UNNUMBERED: notoc +:END: + +#+attr_texinfo: :tag Important +#+begin_quote +If you are using a version of Org that is part of the Emacs +distribution, please skip this section and go directly to [[*Activation]]. +#+end_quote + +If you have downloaded Org from the web, either as a distribution +=.zip= or =.tar= file, or as a Git archive, it is best to run it +directly from the distribution directory. You need to add the =lisp/= +subdirectories to the Emacs load path. To do this, add the following +line to your Emacs init file: + +: (add-to-list 'load-path "~/path/to/orgdir/lisp") + +#+texinfo: @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. + +: make autoloads + +** Activation +:PROPERTIES: +:UNNUMBERED: notoc +:END: + +Add the following lines to your Emacs init file to define /global/ +keys for three commands that are useful in any Emacs buffer, not just +Org buffers. Please choose suitable keys yourself. + +#+begin_src emacs-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_src + +Files with extension =.org= will be put into Org mode automatically. + +** Feedback +:PROPERTIES: +:UNNUMBERED: notoc +:END: + +If you find problems with Org, or if you have questions, remarks, or +ideas about it, please mail to the Org mailing list +mailto:emacs-orgmode@gnu.org. For information on how to submit bug +reports, see the main manual. + +* Document Structure +:PROPERTIES: +:DESCRIPTION: A tree works like your brain. +:END: + +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, +~org-cycle~, which is bound to the {{{kbd(TAB)}}} key. + +** Headlines +:PROPERTIES: +:DESCRIPTION: How to typeset Org tree nodes. +:END: + +Headlines define the structure of an outline tree. The headlines in +Org start on the left margin[fn:1] with one or more stars followed by +a space. For example: + +#+begin_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 ~org-footnote-section~, which +defaults to =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 [[*Miscellaneous]] for a setup to realize this. + +** Visibility Cycling +:PROPERTIES: +:DESCRIPTION: Show and hide, much simplified. +:END: + +Outlines make it possible to hide parts of the text in the buffer. +Org uses just two commands, bound to {{{kbd(TAB)}}} and +{{{kbd{S-TAB)}}} to change the visibility in the buffer. + +#+attr_texinfo: :sep , +- {{{kbd(TAB)}}} :: + + /Subtree cycling/: Rotate current subtree among the states + + : ,-> FOLDED -> CHILDREN -> SUBTREE --. + : '-----------------------------------' + + When called with a prefix argument ({{{kbd(C-u TAB)}}}), or with the + Shift key, global cycling is invoked. + +- {{{kbd(S-TAB)}}}, {{{kbd(C-u TAB)}}} :: + + /Global cycling/: Rotate the entire buffer among the states + + : ,-> OVERVIEW -> CONTENTS -> SHOW ALL --. + : '--------------------------------------' + +- {{{kbd(C-u C-u C-u TAB)}}} :: + + Show all, including drawers. + +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 ~org-startup-folded~, or on a per-file +basis by adding a =STARTUP= keyword to =overview=, =content=, +=showall=, =showeverything= or =show<n>levels= (n = 2..5) like this: + +: #+STARTUP: content + +** Motion +:PROPERTIES: +:DESCRIPTION: Jumping to other headlines. +:END: + +The following commands jump to other headlines in the buffer. + +- {{{kbd(C-c C-n)}}} :: Next heading. + +- {{{kbd(C-c C-p)}}} :: Previous heading. + +- {{{kbd(C-c C-f)}}} :: Next heading same level. + +- {{{kbd(C-c C-b)}}} :: Previous heading same level. + +- {{{kbd(C-c C-u)}}} :: Backward to higher level heading. + +** Structure Editing +:PROPERTIES: +:DESCRIPTION: Changing sequence and level of headlines. +:END: + +#+attr_texinfo: :sep , +- {{{kbd(M-RET)}}} :: + + Insert new heading with same level as current. If point is in + a plain list item, a new item is created (see [[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[fn:2]. + +- {{{kbd(M-S-RET)}}} :: + + Insert new TODO entry with same level as current heading. + +- {{{kbd(TAB)}}} in new, empty entry :: + + In a new entry with no text yet, {{{kbd(TAB)}}} cycles through + reasonable levels. + +- {{{kbd(M-LEFT)}}}, {{{kbd(M-RIGHT)}}} :: + + Promote or demote current heading by one level. + +- {{{kbd(M-UP)}}}, {{{kbd(M-DOWN)}}} :: + + Move subtree up or down, i.e., swap with previous or next subtree of + same level. + +- {{{kbd(C-c C-w)}}} :: + + Refile entry or region to a different location. See [[*Refile and + Copy]]. + +- {{{kbd(C-x n s)}}}, {{{kbd(C-x n w)}}} :: + + Narrow buffer to current subtree and widen it again. + +When there is an active region (Transient Mark mode), promotion and +demotion work on all headlines in the region. + +** Sparse Trees +:PROPERTIES: +:DESCRIPTION: Matches embedded in context. +:END: + +An important feature of Org mode is the ability to construct /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[fn:3]. +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: + +- {{{kbd(C-c /)}}} :: + + This prompts for an extra key to select a sparse-tree creating + command. + +- {{{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. + +** Plain Lists +:PROPERTIES: +:DESCRIPTION: Additional structure within an entry. +:END: + +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 [[*Checkboxes]]). Org supports editing such lists, and +every exporter (see [[*Exporting]]) can parse and format them. + +Org knows ordered lists, unordered lists, and description lists. + +#+attr_texinfo: :indic @bullet +- /Unordered/ list items start with =-=, =+=, or =*= as bullets. + +- /Ordered/ list items start with =1.=, or =1)=. + +- /Description/ list use =::= to separate the /term/ from the + description. + +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: + +#+begin_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). + +#+attr_texinfo: :sep , +- {{{kbd(TAB)}}} :: + + Items can be folded just like headline levels. + +- {{{kbd(M-RET)}}} :: + + Insert new item at current level. With a prefix argument, force + a new heading (see [[*Structure Editing]]). + +- {{{kbd(M-S-RET)}}} :: + + Insert a new item with a checkbox (see [[*Checkboxes]]). + +- {{{kbd(M-S-UP)}}}, {{{kbd(M-S-DOWN)}}} :: + + Move the item including subitems up/down (swap with previous/next + item of same indentation). If the list is ordered, renumbering is + automatic. + +- {{{kbd(M-LEFT)}}}, {{{kbd(M-RIGHT)}}} :: + + Decrease/increase the indentation of an item, leaving children + alone. + +- {{{kbd(M-S-LEFT)}}}, {{{kbd(M-S-RIGHT)}}} :: + + Decrease/increase the indentation of the item, including subitems. + +- {{{kbd(C-c C-c)}}} :: + + If there is a checkbox (see [[*Checkboxes]]) in the item line, toggle + the state of the checkbox. Also verify bullets and indentation + consistency in the whole list. + +- {{{kbd(C-c -)}}} :: + + Cycle the entire list level through the different itemize/enumerate + bullets (=-=, =+=, =*=, =1.=, =1)=). + +* Tables +:PROPERTIES: +:DESCRIPTION: Pure magic for quick formatting. +:END: + +Org comes with a fast and intuitive table editor. Spreadsheet-like +calculations are supported in connection with the Emacs Calc package +(see [[info:calc][GNU Emacs Calculator Manual]]). + +Org makes it easy to format tables in plain ASCII. Any line with =|= +as the first non-whitespace character is considered part of a table. +=|= is also the column separator. A table might look like this: + +#+begin_example +| Name | Phone | Age | +|-------+-------+-----| +| Peter | 1234 | 17 | +| Anna | 4321 | 25 | +#+end_example + +A table is re-aligned automatically each time you press {{{kbd(TAB)}}} +or {{{kbd(RET)}}} or {{{kbd(C-c C-c)}}} inside the table. +{{{kbd(TAB)}}} also moves to the next field ({{{kbd(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 =|-= 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 + +: |Name|Phone|Age| +: |- + +#+texinfo: @noindent +and then press {{{kbd(TAB)}}} to align the table and start filling in +fields. Even faster would be to type =|Name|Phone|Age= followed by +{{{kbd(C-c 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 /immediately after point was moved into a new field with +{{{kbd(TAB)}}}, {{{kbd(S-TAB)}}} or {{{kbd(RET)}}}/, the field is +automatically made blank. + +** Creation and conversion +:PROPERTIES: +:UNNUMBERED: notoc +:END: + +- {{{kbd(C-c |)}}} :: + + Convert the active region to table. If every line contains at least + one {{{kbd(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 RET | - TAB)}}}. + +** Re-aligning and field motion +:PROPERTIES: +:UNNUMBERED: notoc +:END: + +#+attr_texinfo: :sep , +- {{{kbd(C-c C-c)}}} :: + + Re-align the table without moving point. + +- {{{kbd(TAB)}}} :: + + Re-align the table, move to the next field. Creates a new row if + necessary. + +- {{{kbd(S-TAB)}}} :: + + Re-align, move to previous field. + +- {{{kbd(RET)}}} :: + + Re-align the table and move down to next row. Creates a new row if + necessary. + +- {{{kbd(S-UP)}}}, {{{kbd(S-DOWN)}}}, {{{kbd(S-LEFT)}}}, {{{kbd(S-RIGHT)}}} :: + + Move a cell up, down, left, and right by swapping with adjacent + cell. + +** Column and row editing +:PROPERTIES: +:UNNUMBERED: notoc +:END: + +- {{{kbd(M-LEFT)}}}, {{{kbd(M-RIGHT)}}} :: + + Move the current column left/right. + +- {{{kbd(M-S-LEFT)}}} :: + + Kill the current column. + +- {{{kbd(M-S-RIGHT)}}} :: + + Insert a new column to the left of point position. + +- {{{kbd(M-UP)}}}, {{{kbd(M-DOWN)}}} :: + + Move the current row up/down. + +- {{{kbd(M-S-UP)}}} :: + + Kill the current row or horizontal line. + +- {{{kbd(M-S-DOWN)}}} :: + + Insert a new row above the current row. With a prefix argument, the + line is created below the current one. + +- {{{kbd(C-c -)}}} :: + + Insert a horizontal line below current row. With a prefix argument, + the line is created above the current line. + +- {{{kbd(C-c RET)}}} :: + + Insert a horizontal line below current row, and move the point into + the row below that line. + +- {{{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. + +* Hyperlinks +:PROPERTIES: +:DESCRIPTION: Notes in context. +:END: + +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: + +: [[LINK][DESCRIPTION]] + +#+texinfo: @noindent +or alternatively + +: [[LINK]] + +Once a link in the buffer is complete, with all brackets present, Org +changes the display so that =DESCRIPTION= is displayed instead of +=[[LINK][DESCRIPTION]]= and =LINK= is displayed instead of =[[LINK]]=. +To edit the invisible {{{var(LINK)}}} part, use {{{kbd(C-c C-l)}}} +with the point on the link. + +** Internal links +:PROPERTIES: +:UNNUMBERED: notoc +:END: + +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 +=[[#my-custom-id]]= which links to the entry with the =CUSTOM_ID= property +=my-custom-id=. + +Links such as =[[My Target]]= or =[[My Target][Find my target]]= lead +to a text search in the current file for the corresponding target, +which looks like =<<My Target>>=. + +** External Links +:PROPERTIES: +:UNNUMBERED: notoc +:END: + +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: + +| =http://www.astro.uva.nl/=dominik= | on the web | +| =file:/home/dominik/images/jupiter.jpg= | file, absolute path | +| =/home/dominik/images/jupiter.jpg= | same as above | +| =file:papers/last.pdf= | file, relative path | +| =./papers/last.pdf= | same as above | +| =file:projects.org= | another Org file | +| =docview:papers/last.pdf::NNN= | open in DocView mode at page {{{var(NNN)}}} | +| =id:B7423F4D-2E8A-471B-8810-C40F074717E9= | link to heading by ID | +| =news:comp.emacs= | Usenet link | +| =mailto:adent@galaxy.net= | mail link | +| =mhe:folder#id= | MH-E message link | +| =rmail:folder#id= | Rmail message link | +| =gnus:group#id= | Gnus article link | +| =bbdb:R.*Stallman= | BBDB link (with regexp) | +| =irc:/irc.com/#emacs/bob= | IRC link | +| =info:org#Hyperlinks= | Info node link | + +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: + +| =file:~/code/main.c::255= | Find line 255 | +| =file:~/xx.org::My Target= | Find =<<My Target>>= | +| =[[file:~/xx.org::#my-custom-id]]= | Find entry with a custom ID | + +** Handling Links +:PROPERTIES: +:UNNUMBERED: notoc +:END: + +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 ~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 [[*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. + +#+attr_texinfo: :sep , +- {{{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(UP)}}} + and {{{kbd(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. + +- {{{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. + +- {{{kbd(C-c C-o)}}} :: + + Open link at point. + +- {{{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. + +* TODO Items +:PROPERTIES: +:DESCRIPTION: Every tree branch can be a TODO item. +:END: + +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. + +** Basic TODO Functionality +:PROPERTIES: +:DESCRIPTION: Marking and displaying TODO entries. +:ALT_TITLE: TODO Basics +:END: + +Any headline becomes a TODO item when it starts with the word =TODO=, +for example: + +: *** TODO Write letter to Sam Fortune + +The most important commands to work with TODO entries are: + +#+attr_texinfo: :sep , +- {{{kbd(C-c C-t)}}} :: + + Rotate the TODO state of the current item among + + : ,-> (unmarked) -> TODO -> DONE --. + : '--------------------------------' + + The same rotation can also be done "remotely" from the agenda buffer + with the {{{kbd(t)}}} command key (see [[*Commands in the Agenda + Buffer]]). + +- {{{kbd(S-RIGHT)}}}, {{{kbd(S-LEFT)}}} :: + + Select the following/preceding TODO state, similar to cycling. + +- {{{kbd(C-c / t)}}} :: + + View TODO items in a /sparse tree/ (see [[*Sparse Trees]]). Folds the + entire buffer, but shows all TODO items---with not-DONE state---and + the headings hierarchy above them. + +- {{{kbd(M-x org-agenda t)}}} :: + + Show the global TODO list. Collects the TODO items (with not-DONE + states) from all agenda files (see [[*Agenda Views]]) into a single + buffer. See [[*The Global TODO List]], for more information. + +- {{{kbd(S-M-RET)}}} :: + + Insert a new TODO entry below the current one. + +Changing a TODO state can also trigger tag changes. See the docstring +of the option ~org-todo-state-tags-triggers~ for details. + +** Multi-state Workflow +:PROPERTIES: +:DESCRIPTION: More than just on/off. +:END: + +You can use TODO keywords to indicate @emph{sequential} working progress +states: + +#+begin_src emacs-lisp +(setq org-todo-keywords + '((sequence "TODO" "FEEDBACK" "VERIFY" "|" "DONE" "DELEGATED"))) +#+end_src + +#+texinfo: @noindent +The vertical bar separates the =TODO= keywords (states that /need +action/) from the =DONE= states (which need /no further action/). If +you do not provide the separator bar, the last state is used as the +=DONE= state. With this setup, the command {{{kbd(C-c C-t)}}} cycles +an entry from =TODO= to =FEEDBACK=, then to =VERIFY=, and finally to +=DONE= and =DELEGATED=. + +Sometimes you may want to use different sets of TODO keywords in +parallel. For example, you may want to have the basic =TODO=/=DONE=, +but also a workflow for bug fixing. Your setup would then look like +this: + +#+begin_src emacs-lisp +(setq org-todo-keywords + '((sequence "TODO(t)" "|" "DONE(d)") + (sequence "REPORT(r)" "BUG(b)" "KNOWNCAUSE(k)" "|" "FIXED(f)"))) +#+end_src + +#+texinfo: @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. + +#+begin_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. + +** Progress Logging +:PROPERTIES: +:DESCRIPTION: Dates and notes for progress. +:END: + +To record a timestamp and a note when changing a TODO state, call the +command ~org-todo~ with a prefix argument. + +#+attr_texinfo: :sep , +- {{{kbd(C-u C-c C-t)}}} :: + Prompt for a note and record a the time of the TODO state change. + +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 [[*Clocking Work Time]]. + +*** Closing items +:PROPERTIES: +:UNNUMBERED: notoc +:END: + +The most basic logging is to keep track of /when/ a certain TODO item +was marked as done. This can be achieved with[fn:4] + +#+begin_src emacs-lisp +(setq org-log-done 'time) +#+end_src + +#+texinfo: @noindent +Then each time you turn an entry from a TODO (not-done) state into any +of the DONE states, a line =CLOSED: [timestamp]= is inserted just +after the headline. + +If you want to record a note along with the timestamp, use[fn:5] + +#+begin_src emacs-lisp +(setq org-log-done 'note) +#+end_src + +#+texinfo: @noindent +You are then be prompted for a note, and that note is stored below the +entry with a =Closing Note= heading. + +*** Tracking TODO state changes +:PROPERTIES: +:UNNUMBERED: notoc +:END: + +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 ~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 =!= (for +a timestamp) and =@= (for a note) in parentheses after each keyword. +For example: + +: #+TODO: TODO(t) WAIT(w@/!) | DONE(d!) CANCELED(c@) + +#+texinfo: @noindent +defines TODO keywords and fast access keys, and also request that +a time is recorded when the entry is set to =DONE=, and that a note is +recorded when switching to =WAIT= or =CANCELED=. The same syntax +works also when setting ~org-todo-keywords~. + +** Priorities +:PROPERTIES: +:DESCRIPTION: Some things are more important than others. +:END: + +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 /priority cookie/ into the headline of a TODO item, +like this + +: *** TODO [#A] Write letter to Sam Fortune + +Org mode supports three priorities: =A=, =B=, and =C=. =A= is the +highest, =B= the default if none is given. Priorities make +a difference only in the agenda. + +#+attr_texinfo: :sep ; +- {{{kbd(C-c \,)}}} :: + + Set the priority of the current headline. Press {{{kbd(A)}}}, + {{{kbd(B)}}} or {{{kbd(C)}}} to select a priority, or {{{kbd(SPC)}}} + to remove the cookie. + +- {{{kbd(S-UP)}}} (~org-priority-up~); {{{kbd(S-DOWN)}}} (~org-priority-down~) :: + + Increase/decrease the priority of the current headline. + +** Breaking Tasks Down into Subtasks +:PROPERTIES: +:DESCRIPTION: Splitting a task into manageable pieces. +:ALT_TITLE: Breaking Down Tasks +:END: + +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 =[/]= or =[%]= 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: + +#+begin_example +,* Organize Party [33%] +,** TODO Call people [1/2] +,*** TODO Peter +,*** DONE Sarah +,** TODO Buy food +,** DONE Talk to neighbor +#+end_example + +** Checkboxes +:PROPERTIES: +:DESCRIPTION: Tick-off lists. +:END: + +Every item in a plain list (see [[*Plain Lists]]) can be made into +a checkbox by starting it with the string =[ ]=. 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. + +#+begin_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: + +- {{{kbd(C-c C-c)}}} :: + + Toggle checkbox status or---with prefix argument---checkbox presence + at point. + +- {{{kbd(M-S-RET)}}} :: + + Insert a new item with a checkbox. This works only if point is + already in a plain list item (see [[*Plain Lists]]). + +* Tags +:PROPERTIES: +:DESCRIPTION: Tagging headlines and matching sets of tags. +:END: + +An excellent way to implement labels and contexts for +cross-correlating information is to assign /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, =_=, +and =@=. Tags must be preceded and followed by a single colon, e.g., +=:work:=. Several tags can be specified, as in =:work:urgent:=. Tags +by default are in bold face with the same color as the headline. + +** Tag inheritance +:PROPERTIES: +:UNNUMBERED: notoc +:END: + +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 + +#+begin_example +,* Meeting with the French group :work: +,** Summary by Frank :boss:notes: +,*** TODO Prepare slides for him :action: +#+end_example + +#+texinfo: @noindent +the final heading has the tags =work=, =boss=, =notes=, and =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[fn:6]: + +: #+FILETAGS: :Peter:Boss:Secret: + +** Setting tags +:PROPERTIES: +:UNNUMBERED: notoc +:END: + +Tags can simply be typed into the buffer at the end of a headline. +After a colon, {{{kbd(M-TAB)}}} offers completion on tags. There is +also a special command for inserting tags: + +- {{{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. + +- {{{kbd(C-c C-c)}}} :: + + When point is in a headline, this does the same as {{{kbd(C-c + C-q)}}}. + +Org supports tag insertion based on a /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 ~org-tag-alist~. Finally you can set the default tags +for a given file using the =TAGS= keyword, like + +: #+TAGS: @work @home @tennisclub +: #+TAGS: laptop car pc sailboat + +By default Org mode uses the standard minibuffer completion facilities +for entering tags. However, it also implements another, quicker, tag +selection method called /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 +~org-tag-alist~ in your Emacs init file. For example, you may find +the need to tag many items in different files with =@home=. In this +case you can set something like: + +#+begin_src emacs-lisp +(setq org-tag-alist '(("@work" . ?w) ("@home" . ?h) ("laptop" . ?l))) +#+end_src + +If the tag is only relevant to the file you are working on, then you +can instead set the =TAGS= keyword as: + +: #+TAGS: @work(w) @home(h) @tennisclub(t) laptop(l) pc(p) + +** Tag groups +:PROPERTIES: +:UNNUMBERED: notoc +:END: + +A tag can be defined as a /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: + +: #+TAGS: [ GTD : Control Persp ] + +#+texinfo: @noindent +or, if tags in the group should be mutually exclusive: + +: #+TAGS: { Context : @Home @Work } + +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 ~org-toggle-tags-groups~, bound to {{{kbd(C-c C-x q)}}}. + +** Tag searches +:PROPERTIES: +:UNNUMBERED: notoc +:END: + +- {{{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. + +- {{{kbd(M-x org-agenda m)}}} :: + + Create a global list of tag matches from all agenda files. See + [[*Matching Tags and Properties]]. + +- {{{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 + ~org-tags-match-list-sublevels~). + +These commands all prompt for a match string which allows basic +Boolean logic like =+boss+urgent-project1=, to find entries with tags +=boss= and =urgent=, but not =project1=, or =Kathy|Sally= to find +entries which are tagged, like =Kathy= or =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 [[*Matching Tags and Properties]]. + +* Properties +:PROPERTIES: +:DESCRIPTION: Storing information about an entry. +:END: + +Properties are key-value pairs associated with an entry. They live in +a special drawer with the name =PROPERTIES=. Each property is +specified on a single line, with the key (surrounded by colons) first, +and the value after it: + +#+begin_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 =Xyz= by +setting a property =Xyz_ALL=. This special property is /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: + +#+begin_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: + +: #+PROPERTY: NDisks_ALL 1 2 3 4 + +The following commands help to work with properties: + +- {{{kbd(C-c C-x p)}}} :: + + Set a property. This prompts for a property name and a value. + +- {{{kbd(C-c C-c d)}}} :: + + Remove a property from the current entry. + +To create sparse trees and special lists with selection based on +properties, the same commands are used as for tag searches (see +[[*Tags]]). The syntax for the search string is described in [[*Matching +Tags and Properties]]. + +* Dates and Times +:PROPERTIES: +:DESCRIPTION: Making items useful for planning. +:END: + +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 /timestamp/ in Org mode. + +** Timestamps +:PROPERTIES: +:DESCRIPTION: Assigning a time to a tree entry. +:END: + +A timestamp is a specification of a date---possibly with a time or +a range of times---in a special format, either =<2003-09-16 Tue>= or +=<2003-09-16 Tue 09:39>= or =<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 [[*The Weekly/daily Agenda]]). We distinguish: + +- 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. + + #+begin_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 + +- Timestamp with repeater interval :: + + A timestamp may contain a /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: + + #+begin_example + ,* Pick up Sam at school + <2007-05-16 Wed 12:30 +1w> + #+end_example + +- 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: + + #+begin_example + ,* 22:00-23:00 The nerd meeting on every 2nd Thursday of the month + <%%(diary-float t 4 2)> + #+end_example + +- Time/Date range :: + + Two timestamps connected by =--= denote a range. + + #+begin_example + ,** Meeting in Amsterdam + <2004-08-23 Mon>--<2004-08-26 Thu> + #+end_example + +- 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 /not/ trigger an entry to show up in the agenda. + + #+begin_example + ,* Gillian comes late for the fifth time + [2006-11-01 Wed] + #+end_example + +** Creating Timestamps +:PROPERTIES: +:DESCRIPTION: Commands that insert timestamps. +:END: + +For Org mode to recognize timestamps, they need to be in the specific +format. All commands listed below produce timestamps in the correct +format. + +#+attr_texinfo: :sep , +- {{{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. + +- {{{kbd(C-c !)}}} :: + + Like {{{kbd(C-c .)}}}, but insert an inactive timestamp that does + not cause an agenda entry. + +- {{{kbd(S-LEFT)}}}, {{{kbd(S-RIGHT)}}} :: + + Change date at point by one day. + +- {{{kbd(S-UP)}}}, {{{kbd(S-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 =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. + + +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. + +** Deadlines and Scheduling +:PROPERTIES: +:DESCRIPTION: Planning your work. +:END: + +A timestamp may be preceded by special keywords to facilitate +planning: + +- {{{kbd(C-c C-d)}}} :: + + Insert =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 /today/ carries a warning about the + approaching or missed deadline, starting ~org-deadline-warning-days~ + before the due date, and continuing until the entry is marked as + done. An example: + + #+begin_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 + +- {{{kbd(C-c C-s)}}} :: + + Insert =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[fn:7]. + + The headline is listed under the given date[fn:8]. In addition, + a reminder that the scheduled date has passed is present in the + compilation for /today/, until the entry is marked as done, i.e., + the task is automatically forwarded until completed. + + #+begin_example + ,*** TODO Call Trillian for a date on New Years Eve. + SCHEDULED: <2004-12-25 Sat> + #+end_example + +Some tasks need to be repeated again and again. Org mode helps to +organize such tasks using a so-called repeater in a =DEADLINE=, +=SCHEDULED=, or plain timestamps. In the following example: + +#+begin_example +,** TODO Pay the rent + DEADLINE: <2005-10-01 Sat +1m> +#+end_example + +#+texinfo: @noindent +the =+1m= is a repeater; the intended interpretation is that the task +has a deadline on =<2005-10-01>= and repeats itself every (one) month +starting from that time. + +** Clocking Work Time +:PROPERTIES: +:DESCRIPTION: Tracking how long you spent on a task. +:END: + +Org mode allows you to clock the time you spend on specific tasks in +a project. + +#+attr_texinfo: :sep , +- {{{kbd(C-c C-x C-i)}}} :: + + Start the clock on the current item (clock-in). This inserts the + =CLOCK= keyword together with a timestamp. When called with + a {{{kbd(C-u)}}} prefix argument, select the task from a list of + recently clocked tasks. + +- {{{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 + ==>HH:MM=. + +- {{{kbd(C-c C-x C-e)}}} :: + + Update the effort estimate for the current clock task. + +- {{{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. + +- {{{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. + +The {{{kbd(l)}}} key may be used in the agenda (see [[*The Weekly/daily +Agenda]]) to show which tasks have been worked on or closed during +a day. + +* Capture, Refile, Archive +:PROPERTIES: +:DESCRIPTION: The ins and outs for projects. +:END: + +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 /capture/. It also can +store files related to a task (/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. + +** Capture +:PROPERTIES: +:DESCRIPTION: Capturing new stuff. +:END: + +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. + +*** Setting up capture +:PROPERTIES: +:UNNUMBERED: notoc +:END: + +The following customization sets a default target[fn:9] file for notes. + +#+begin_src emacs-lisp +(setq org-default-notes-file (concat org-directory "/notes.org")) +#+end_src + +You may also define a global key for capturing new material (see +[[*Activation]]). + +*** Using capture +:PROPERTIES: +:UNNUMBERED: notoc +:END: + +- {{{kbd(M-x org-capture)}}} :: + + Start a capture process, placing you into a narrowed indirect buffer + to edit. + +- {{{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. + +- {{{kbd(C-c C-w)}}} :: + + Finalize the capture process by refiling the note to a different + place (see [[*Refile and Copy]]). + +- {{{kbd(C-c C-k)}}} :: + + Abort the capture process and return to the previous state. + +*** Capture templates +:PROPERTIES: +:UNNUMBERED: notoc +:END: + +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 =Tasks= in your file =~/org/gtd.org=. Also, a date tree +in the file =journal.org= should capture journal entries. A possible +configuration would look like: + +#+begin_src emacs-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_src + +If you then press {{{kbd(t)}}} from the capture menu, Org will prepare +the template for you like this: + +: * TODO +: [[file:LINK TO WHERE YOU INITIATED CAPTURE]] + +#+texinfo: @noindent +During expansion of the template, special %-escapes[fn:10] allow +dynamic insertion of content. Here is a small selection of the +possibilities, consult the manual for more. + +| =%a= | annotation, normally the link created with ~org-store-link~ | +| =%i= | initial content, the region when capture is called with {{{kbd(C-u)}}} | +| =%t=, =%T= | timestamp, date only, or date and time | +| =%u=, =%U= | like above, but inactive timestamps | +| =%?= | after completing the template, position point here | + +** Refile and Copy +:PROPERTIES: +:DESCRIPTION: Moving/copying a tree from one place to another. +:END: + +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: + +- {{{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 ~org-refile-targets~ for + details. + +- {{{kbd(C-u C-c C-w)}}} :: + + Use the refile interface to jump to a heading. + +- {{{kbd(C-u C-u C-c C-w)}}} :: + + Jump to the location where ~org-refile~ last moved a tree to. + +- {{{kbd(C-c M-w)}}} :: + + Copying works like refiling, except that the original note is not + deleted. + +** Archiving +:PROPERTIES: +:DESCRIPTION: What to do with finished products. +:END: + +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. + +- {{{kbd(C-c C-x C-a)}}} :: + + Archive the current entry using the command specified in the + variable ~org-archive-default-command~. + +- {{{kbd(C-c C-x C-s)}}} or short {{{kbd(C-c $)}}} :: + + Archive the subtree starting at point position to the location given + by ~org-archive-location~. + +The default archive location is a file in the same directory as the +current file, with the name derived by appending =_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 +~org-archive-location~. + +There is also an in-buffer option for setting this variable, for +example: + +: #+ARCHIVE: %s_done:: + +* Agenda Views +:PROPERTIES: +:DESCRIPTION: Collecting information into views. +:END: + +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 /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 [[*Commands in the Agenda Buffer]]. + +** Agenda Files +:PROPERTIES: +:DESCRIPTION: Files being searched for agenda information. +:END: + +The information to be shown is normally collected from all /agenda +files/, the files listed in the variable ~org-agenda-files~. + +#+attr_texinfo: :sep or +- {{{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. + +- {{{kbd(C-c ])}}} :: + + Remove current file from the list of agenda files. + +- {{{kbd(C-')}}} or {{{kbd(C-\,)}}} :: + + Cycle through agenda file list, visiting one file after the other. + +** The Agenda Dispatcher +:PROPERTIES: +:DESCRIPTION: Keyboard access to agenda views. +:ALT_TITLE: Agenda Dispatcher +:END: + +The views are created through a dispatcher, accessible with {{{kbd(M-x +org-agenda)}}}, or, better, bound to a global key (see [[*Activation]]). +It displays a menu from which an additional letter is required to +execute a command. The dispatcher offers the following default +commands: + +#+attr_texinfo: :sep , +- {{{kbd(a)}}} :: + + Create the calendar-like agenda (see [[*The Weekly/daily Agenda]]). + +- {{{kbd(t)}}}, {{{kbd(T)}}} :: + + Create a list of all TODO items (see [[*The Global TODO List]]). + +- {{{kbd(m)}}}, {{{kbd(M)}}} :: + + Create a list of headlines matching a given expression (see + [[*Matching Tags and Properties]]). + +- {{{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. + +** The Weekly/Daily Agenda +:PROPERTIES: +:DESCRIPTION: What is available out of the box? +:ALT_TITLE: Built-in Agenda Views +:END: + +The purpose of the weekly/daily /agenda/ is to act like a page of +a paper agenda, showing all the tasks for the current week or day. + +- {{{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. + +Org mode understands the syntax of the diary and allows you to use +diary expression entries directly in Org files: + +#+begin_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 +~org-agenda-to-appt~. + +** The Global TODO List +:PROPERTIES: +:DESCRIPTION: All unfinished action items. +:ALT_TITLE: Global TODO List +:END: + +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 [[*Commands in the Agenda +Buffer]]. + +- {{{kbd(M-x org-agenda t)}}} :: + + Show the global TODO list. This collects the TODO items from all + agenda files (see [[*Agenda Views]]) into a single buffer. + +- {{{kbd(M-x org-agenda T)}}} :: + + Like the above, but allows selection of a specific TODO keyword. + +** Matching Tags and Properties +:PROPERTIES: +:DESCRIPTION: Structured information with fine-tuned search. +:END: + +If headlines in the agenda files are marked with /tags/ (see [[*Tags]]), +or have properties (see [[*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)}}}. + +- {{{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 =+work+urgent-withboss= or =work|home= + (see [[*Tags]]). If you often need a specific search, define a custom + command for it (see [[*The Agenda Dispatcher]]). + +- {{{kbd(M-x org-agenda M)}}} :: + + Like {{{kbd(m)}}}, but only select headlines that are also TODO + items. + +A search string can use Boolean operators =&= for AND and =|= for OR. +=&= binds more strongly than =|=. Parentheses are currently not +implemented. Each element in the search is either a tag, a regular +expression matching tags, or an expression like =PROPERTY OPERATOR +VALUE= with a comparison operator, accessing a property value. Each +element may be preceded by =-= to select against it, and =+= is +syntactic sugar for positive selection. The AND operator =&= is +optional when =+= or =-= is present. Here are some examples, using +only tags. + +- =+work-boss= :: + + Select headlines tagged =work=, but discard those also tagged + =boss=. + +- =work|laptop= :: + + Selects lines tagged =work= or =laptop=. + +- =work|laptop+night= :: + + Like before, but require the =laptop= lines to be tagged also + =night=. + +You may also test for properties at the same time as matching tags, +see the manual for more information. + +** Search View +:PROPERTIES: +:DESCRIPTION: Find entries by searching for text. +:END: + +This agenda view is a general text search facility for Org mode +entries. It is particularly useful to find notes. + +- {{{kbd(M-x org-agenda s)}}} (~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. + +For example, the search string =computer equipment= matches entries +that contain =computer equipment= as a substring. + +Search view can also search for specific keywords in the entry, using +Boolean logic. The search string =+computer ++wifi -ethernet -{8\.11[bg]}= matches note entries that contain the +keywords =computer= and =wifi=, but not the keyword =ethernet=, and +which are also not matched by the regular expression =8\.11[bg]=, +meaning to exclude both =8.11b= and =8.11g=. + +Note that in addition to the agenda files, this command also searches +the files listed in ~org-agenda-text-search-extra-files~. + +** Commands in the Agenda Buffer +:PROPERTIES: +:DESCRIPTION: Remote editing of Org trees. +:ALT_TITLE: Agenda Commands +:END: + +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. + +*** Motion +:PROPERTIES: +:UNNUMBERED: notoc +:END: + +- {{{kbd(n)}}} :: + + Next line (same as {{{kbd(DOWN)}}} and {{{kbd(C-n)}}}). + +- {{{kbd(p)}}} :: + + Previous line (same as {{{kbd(UP)}}} and {{{kbd(C-p)}}}). + +*** View/Go to Org file +:PROPERTIES: +:UNNUMBERED: notoc +:END: + +- {{{kbd(SPC)}}} :: + + Display the original location of the item in another window. + With a prefix argument, make sure that drawers stay folded. + +- {{{kbd(TAB)}}} :: + + Go to the original location of the item in another window. + +- {{{kbd(RET)}}} :: + + Go to the original location of the item and delete other windows. + +*** Change display +:PROPERTIES: +:UNNUMBERED: notoc +:END: +#+attr_texinfo: :sep , +- {{{kbd(o)}}} :: + + Delete other windows. + +- {{{kbd(v d)}}} or short {{{kbd(d)}}} :: + + Switch to day view. + +- {{{kbd(v w)}}} or short {{{kbd(w)}}} :: + + Switch to week view. + +- {{{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. + +- {{{kbd(b)}}} :: + + Go backward in time to display earlier dates. + +- {{{kbd(.)}}} :: + + Go to today. + +- {{{kbd(j)}}} :: + + Prompt for a date and go there. + +- {{{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 ~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. + +- {{{kbd(r)}}}, {{{kbd(g)}}} :: + + Recreate the agenda buffer, for example to reflect the changes after + modification of the timestamps of items. + +- {{{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. + +*** Remote editing +:PROPERTIES: +:UNNUMBERED: notoc +:END: + +- {{{kbd(0--9)}}} :: + + Digit argument. + +- {{{kbd(t)}}} :: + + Change the TODO state of the item, both in the agenda and in the + original Org file. + +- {{{kbd(C-k)}}} :: + + Delete the current agenda item along with the entire subtree + belonging to it in the original Org file. + +- {{{kbd(C-c C-w)}}} :: + + Refile the entry at point. + +- {{{kbd(a)}}} :: + + Archive the subtree corresponding to the entry at point using the + default archiving command set in ~org-archive-default-command~. + +- {{{kbd($)}}} :: + + Archive the subtree corresponding to the current headline. + +- {{{kbd(C-c C-s)}}} :: + + Schedule this item. With a prefix argument, remove the + scheduling timestamp + +- {{{kbd(C-c C-d)}}} :: + + Set a deadline for this item. With a prefix argument, remove the + deadline. + +- {{{kbd(S-RIGHT)}}} :: + + Change the timestamp associated with the current line by one day + into the future. + +- {{{kbd(S-LEFT)}}} :: + + Change the timestamp associated with the current line by one day + into the past. + +- {{{kbd(I)}}} :: + + Start the clock on the current item. + +- {{{kbd(O)}}} :: + + Stop the previously started clock. + +- {{{kbd(X)}}} :: + + Cancel the currently running clock. + +- {{{kbd(J)}}} :: + + Jump to the running clock in another window. + +*** Quit and exit +:PROPERTIES: +:UNNUMBERED: notoc +:END: + +- {{{kbd(q)}}} :: + + Quit agenda, remove the agenda buffer. + +- {{{kbd(x)}}} :: + + Exit agenda, remove the agenda buffer and all buffers loaded by + Emacs for the compilation of the agenda. + +** Custom Agenda Views +:PROPERTIES: +:DESCRIPTION: Defining special searches and views. +:END: + +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 +~org-agenda-custom-commands~. You can customize this variable, for +example by pressing {{{kbd(C)}}} from the agenda dispatcher (see [[*The +Agenda Dispatcher]]). You can also directly set it with Emacs Lisp in +the Emacs init file. The following example contains all valid agenda +views: + +#+begin_src emacs-lisp +(setq org-agenda-custom-commands + '(("w" todo "WAITING") + ("u" tags "+boss-urgent") + ("v" tags-todo "+boss-urgent"))) +#+end_src + +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: + +- {{{kbd(w)}}} :: + + as a global search for TODO entries with =WAITING= as the TODO + keyword. + +- {{{kbd(u)}}} :: + + as a global tags search for headlines tagged =boss= but not + =urgent=. + +- {{{kbd(v)}}} :: + + The same search, but limiting it to headlines that are also TODO + items. + +* Markup for Rich Contents +:PROPERTIES: +:DESCRIPTION: Compose beautiful documents. +:ALT_TITLE: Markup +:END: + +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 [[*Exporting]]), you can author +beautiful documents in Org. + +** Paragraphs +:PROPERTIES: +:DESCRIPTION: The basic unit of text. +:END: + +Paragraphs are separated by at least one empty line. If you need to +enforce a line break within a paragraph, use =\\= 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. + +#+begin_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: + +#+begin_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: + +#+begin_example +,#+BEGIN_CENTER +Everything should be made as simple as possible, \\ +but not any simpler +,#+END_CENTER +#+end_example + +** Emphasis and Monospace +:PROPERTIES: +:DESCRIPTION: Bold, italic, etc. +:END: + +You can make words =*bold*=, =/italic/=, =_underlined_=, ==verbatim== +and =~code~=, and, if you must, =+strike-through+=. Text in the code +and verbatim string is not processed for Org specific syntax; it is +exported verbatim. + +** Embedded LaTeX +:PROPERTIES: +:DESCRIPTION: LaTeX can be freely used inside Org documents. +:END: + +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. + +#+begin_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 + +** Literal examples +:PROPERTIES: +:DESCRIPTION: Source code examples with special formatting. +:END: + +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. + +#+begin_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: + +#+begin_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. + +#+begin_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. + +** Images +:PROPERTIES: +:DESCRIPTION: Display an image. +:END: + +An image is a link to an image file that does not have a description +part, for example + +: ./img/cat.jpg + +If you wish to define a caption for the image and maybe a label for +internal cross references (see [[*Hyperlinks]]), make sure that the +link is on a line by itself and precede it with =CAPTION= and =NAME= +keywords as follows: + +#+begin_example +,#+CAPTION: This is the caption for the next figure link (or table) +,#+NAME: fig:SED-HR4049 +[[./img/a.jpg]] +#+end_example + +** Creating Footnotes +:PROPERTIES: +:DESCRIPTION: Edit and read footnotes. +:END: + +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: + +#+begin_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: + +- {{{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. + +- {{{kbd(C-c C-c)}}} :: + + Jump between definition and reference. + +* Exporting +:PROPERTIES: +:DESCRIPTION: Sharing and publishing notes. +:END: + +Org can convert and export documents to a variety of other formats +while retaining as much structure (see [[*Document Structure]]) and markup +(see [[*Markup for Rich Contents]]) as possible. + +** The Export Dispatcher +:PROPERTIES: +:DESCRIPTION: The main interface. +:END: + +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. + +- {{{kbd(C-c C-e)}}} :: + + Invokes the export dispatcher interface. + +Org exports the entire buffer by default. If the Org buffer has an +active region, then Org exports just that region. + +** Export Settings +:PROPERTIES: +:DESCRIPTION: Common export settings. +:END: + +The exporter recognizes special lines in the buffer which provide +additional information. These lines may be put anywhere in the file: + +: #+TITLE: I'm in the Mood for Org + +Most proeminent export options include: + +| =TITLE= | the title to be shown | +| =AUTHOR= | the author (default taken from ~user-full-name~) | +| =DATE= | a date, fixed, or an Org timestamp | +| =EMAIL= | email address (default from ~user-mail-address~) | +| =LANGUAGE= | language code, e.g., =en= | + +Option keyword sets can be inserted from the export dispatcher (see +[[*The Export Dispatcher]]) using the =Insert template= command by +pressing {{{kbd(#)}}}. + +** Table of Contents +:PROPERTIES: +:DESCRIPTION: The if and where of the table of contents. +:END: + +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 +~org-export-with-toc~ variable accordingly. You can achieve the same +on a per file basis, using the following =toc= item in =OPTIONS= +keyword: + +#+begin_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. + +** Include Files +:PROPERTIES: +:DESCRIPTION: Include additional files into a document. +:END: + +During export, you can include the content of another file. For +example, to include your =.emacs= file, you could use: + +: #+INCLUDE: "~/.emacs" src emacs-lisp + +#+texinfo: @noindent +The first parameter is the file name to include. The optional second +parameter specifies the block type: =example=, =export= or =src=. The +optional third parameter specifies the source code language to use for +formatting the contents. This is relevant to both =export= and =src= +block types. + +You can visit the included file with {{{kbd(C-c ')}}}. + +** Comment Lines +:PROPERTIES: +:DESCRIPTION: What will not be exported. +:END: + +Lines starting with zero or more whitespace characters followed by one +=#= and a whitespace are treated as comments and, as such, are not +exported. + +Likewise, regions surrounded by =#+BEGIN_COMMENT= ... =#+END_COMMENT= +are not exported. + +Finally, a =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. + +- {{{kbd(C-c ;)}}} :: + + Toggle the =COMMENT= keyword at the beginning of an entry. + +** ASCII/UTF-8 Export +:PROPERTIES: +:DESCRIPTION: Exporting to flat files with encoding. +:END: + +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. + +#+attr_texinfo: :sep , +- {{{kbd(C-c C-e t a)}}}, {{{kbd(C-c C-e t u)}}} :: + + Export as an ASCII file with a =.txt= extension. For =myfile.org=, + Org exports to =myfile.txt=, overwriting without warning. For + =myfile.txt=, Org exports to =myfile.txt.txt= in order to prevent + data loss. + +** HTML Export +:PROPERTIES: +:DESCRIPTION: Exporting to HTML. +:END: + +Org mode contains an HTML exporter with extensive HTML formatting +compatible with XHTML 1.0 strict standard. + +- {{{kbd(C-c C-e h h)}}} :: + + Export as HTML file with a =.html= extension. For =myfile.org=, Org + exports to =myfile.html=, overwriting without warning. {{{kbd(C-c + C-e h o)}}} exports to HTML and opens it in a web browser. + +The HTML export back-end transforms =<= and =>= to =<= and =>=. +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: +=@@html:...@@=. For example: + +: @@html:<b>@@bold text@@html:</b>@@ + +For larger raw HTML code blocks, use these HTML export code blocks: + +#+begin_example +,#+HTML: Literal HTML code for export + +,#+BEGIN_EXPORT html + All lines between these markers are exported literally +,#+END_EXPORT +#+end_example + +** LaTeX Export +:PROPERTIES: +:DESCRIPTION: Exporting to @LaTeX{} and processing to PDF. +:END: + +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 /article/ class. You can change +this by adding an option like =#+LATEX_CLASS: myclass= in your file. +The class must be listed in ~org-latex-classes~. + +- {{{kbd(C-c C-e l l)}}} :: + + Export to a LaTeX file with a =.tex= extension. For =myfile.org=, + Org exports to =myfile.tex=, overwriting without warning. + +- {{{kbd(C-c C-e l p)}}} :: + + Export as LaTeX file and convert it to PDF file. + +- {{{kbd(C-c C-e l o)}}} :: + + Export as LaTeX file and convert it to PDF, then open the PDF using + the default viewer. + +The LaTeX export back-end can insert any arbitrary LaTeX code, see +[[*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: + +: Code embedded in-line @@latex:any arbitrary LaTeX code@@ in a paragraph. + +Inserting as one or more keyword lines in the Org file: + +: #+LATEX: any arbitrary LaTeX code + +Inserting as an export block in the Org file, where the back-end +exports any code between begin and end markers: + +#+begin_example +,#+BEGIN_EXPORT latex + any arbitrary LaTeX code +,#+END_EXPORT +#+end_example + +** iCalendar Export +:PROPERTIES: +:DESCRIPTION: Exporting to iCalendar. +:END: + +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. + +- {{{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 =.ics=. + +- {{{kbd(C-c C-e c c)}}} :: + + Create a combined iCalendar file from Org files in + ~org-agenda-files~ and write it to + ~org-icalendar-combined-agenda-file~ file name. + +* Publishing +:PROPERTIES: +:DESCRIPTION: Create a web site of linked Org files. +:END: + +Org includes a publishing management system that allows you to +configure automatic HTML conversion of /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: + +#+begin_src emacs-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_src + +- {{{kbd(C-c C-e P x)}}} :: + + Prompt for a specific project and publish all files that belong to + it. + +- {{{kbd(C-c C-e P p)}}} :: + + Publish the project containing the current file. + +- {{{kbd(C-c C-e P f)}}} :: + + Publish only the current file. + +- {{{kbd(C-c C-e P a)}}} :: + + Publish every project. + +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. + +* Working with Source Code +:PROPERTIES: +:DESCRIPTION: Export, evaluate, and tangle code blocks. +:END: + +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: + +#+begin_example +,#+NAME: <name> +,#+BEGIN_SRC <language> <switches> <header arguments> + <body> +,#+END_SRC +#+end_example + +#+texinfo: @noindent +where: + +- =<name>= is a string used to uniquely name the code block, + +- =<language>= specifies the language of the code block, e.g., + =emacs-lisp=, =shell=, =R=, =python=, etc., + +- =<switches>= can be used to control export of the code block, + +- =<header arguments>= can be used to control many aspects of code + block behavior as demonstrated below, + +- =<body>= contains the actual source code. + +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. + +** Using header arguments +:PROPERTIES: +:UNNUMBERED: notoc +:END: + +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. + +- System-wide header arguments :: + + Those are specified by customizing ~org-babel-default-header-args~ + variable, or, for a specific language {{{var(LANG)}}} + ~org-babel-default-header-args:LANG~. + +- Header arguments in properties :: + + You can set them using =header-args= property (see [[*Properties]])---or + =header-args:LANG= for language {{{var(LANG)}}}. Header arguments + set through properties drawers apply at the sub-tree level on down. + +- Header arguments in code blocks :: + + Header arguments are most commonly set at the source code block + level, on the =BEGIN_SRC= line: + + #+begin_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 =HEADER= + keyword on each line. + +** Evaluating code blocks +:PROPERTIES: +:UNNUMBERED: notoc +:END: + +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 =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. + +#+begin_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 =var= header argument. + +: :var NAME=ASSIGN + +#+texinfo: @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. + +** Results of evaluation +:PROPERTIES: +:UNNUMBERED: notoc +:END: + +How Org handles results of a code block execution depends on many +header arguments working together. The primary determinant, however, +is the =results= header argument. It controls the /collection/, +/type/, /format/, and /handling/ of code block results. + +- Collection :: + + How the results should be collected from the code block. You may + choose either =output= or =value= (the default). + +- Type :: + + What result types to expect from the execution of the code block. + You may choose among =table=, =list=, =scalar=, and =file=. Org + tries to guess it if you do not provide it. + +- Format :: + + How Org processes results. Some possible values are =code=, + =drawer=, =html=, =latex=, =link=, and =raw=. + +- Handling :: + + How to insert the results once properly formatted. Allowed values + are =silent=, =replace= (the default), =append=, or =prepend=. + +Code blocks which output results to files---e.g.: graphs, diagrams and +figures---can accept a =: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. + +** Exporting code blocks +:PROPERTIES: +:UNNUMBERED: notoc +:END: + +It is possible to export the /code/ of code blocks, the /results/ of +code block evaluation, /both/ the code and the results of code block +evaluation, or /none/. Org defaults to exporting /code/ for most +languages. + +The =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 =code=, =results=, =both= or =none=. + +** Extracting source code +:PROPERTIES: +:UNNUMBERED: notoc +:END: + +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 ~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 =tangle= header argument, see the manual for +details. + +* Miscellaneous +:PROPERTIES: +:DESCRIPTION: All the rest which did not fit elsewhere. +:END: + +** Completion +:PROPERTIES: +:UNNUMBERED: notoc +:END: + +Org has in-buffer completions with {{{kbd(M-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 =\=, TODO +keywords at the beginning of a headline, and tags after =:= in +a headline. + + +** Structure Templates +:PROPERTIES: +:UNNUMBERED: notoc +:END: + +To quickly insert empty structural blocks, such as =#+BEGIN_SRC= +... =#+END_SRC=, or to wrap existing text in such a block, use + +- {{{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. + +** Clean view +:PROPERTIES: +:UNNUMBERED: notoc +:END: + +Org's default outline with stars and no indents can become too +cluttered for short documents. For /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: + +#+begin_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 RET)}}}), which prepends +intangible space to each line. You can turn on Org Indent mode for +all files by customizing the variable ~org-startup-indented~, or you +can turn it on for individual files using + +: #+STARTUP: indent + +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(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 + +: #+STARTUP: hidestars odd + +* Export Setup :noexport: + +#+setupfile: doc-setup.org + +#+export_file_name: orgguide.texi + +#+texinfo_dir_category: Emacs editing modes +#+texinfo_dir_title: Org Guide: (orgguide) +#+texinfo_dir_desc: Abbreviated Org mode manual + +* Footnotes + +[fn:1] See the variable ~org-special-ctrl-a/e~ to configure special +behavior of {{{kbd(C-a)}}} and {{{kbd(C-e)}}} in headlines. + +[fn:2] If you do not want the line to be split, customize the variable +~org-M-RET-may-split-line~. + +[fn:3] See also the variable ~org-show-context-detail~ to decide how +much context is shown around each match. + +[fn:4] The corresponding in-buffer setting is =#+STARTUP: logdone=. + +[fn:5] The corresponding in-buffer setting is =#+STARTUP: +logenotedone=. + +[fn:6] As with all these in-buffer settings, pressing {{{kbd(C-c +C-c)}}} activates any changes in the line. + +[fn:7] This is quite different from what is normally understood by +/scheduling a meeting/, which is done in Org by just inserting a time +stamp without keyword. + +[fn:8] It will still be listed on that date after it has been marked +as done. If you do not like this, set the variable +~org-agenda-skip-scheduled-if-done~. + +[fn:9] Using capture templates, you get finer control over capture +locations. See [[*Capture templates]]. + +[fn:10] If you need one of these sequences literally, escape the =%= +with a backslash. |