diff options
Diffstat (limited to 'elpa/org-9.5.2/orgguide.info')
| -rw-r--r-- | elpa/org-9.5.2/orgguide.info | 2642 |
1 files changed, 0 insertions, 2642 deletions
diff --git a/elpa/org-9.5.2/orgguide.info b/elpa/org-9.5.2/orgguide.info deleted file mode 100644 index d0eaa5f..0000000 --- a/elpa/org-9.5.2/orgguide.info +++ /dev/null @@ -1,2642 +0,0 @@ -This is orgguide.info, produced by makeinfo version 6.7 from -orgguide.texi. - -Copyright © 2004–2021 Free Software Foundation, Inc. - - 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.” - -INFO-DIR-SECTION Emacs editing modes -START-INFO-DIR-ENTRY -* Org Guide: (orgguide). Abbreviated Org mode manual. -END-INFO-DIR-ENTRY - - -File: orgguide.info, Node: Top, Next: Introduction, Up: (dir) - -Org Mode Compact Guide -********************** - -Copyright © 2004–2021 Free Software Foundation, Inc. - - 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.” - -* 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. - -— 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. - - - -File: orgguide.info, Node: Introduction, Next: Document Structure, Prev: Top, Up: Top - -1 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 *note -comprehensive Org mode manual: (org)Top. 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 -============ - - Important: If you are using a version of Org that is part of the - Emacs distribution, please skip this section and go directly to - *note Activation::. - - 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") - -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 -========== - -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. - - (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) - - Files with extension ‘.org’ will be put into Org mode automatically. - -Feedback -======== - -If you find problems with Org, or if you have questions, remarks, or -ideas about it, please mail to the Org mailing list -<emacs-orgmode@gnu.org>. For information on how to submit bug reports, -see the main manual. - - -File: orgguide.info, Node: Document Structure, Next: Tables, Prev: Introduction, Up: Top - -2 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, ‘org-cycle’, which is -bound to the ‘<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. - - -File: orgguide.info, Node: Headlines, Next: Visibility Cycling, Up: Document Structure - -2.1 Headlines -============= - -Headlines define the structure of an outline tree. The headlines in Org -start on the left margin(1) with one or more stars followed by a space. -For example: - - * Top level headline - ** Second level - *** Third level - some text - *** Third level - more text - * Another top level headline - - 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 -*note Miscellaneous:: for a setup to realize this. - - ---------- Footnotes ---------- - - (1) See the variable ‘org-special-ctrl-a/e’ to configure special -behavior of ‘C-a’ and ‘C-e’ in headlines. - - -File: orgguide.info, Node: Visibility Cycling, Next: Motion, Prev: Headlines, Up: Document Structure - -2.2 Visibility Cycling -====================== - -Outlines make it possible to hide parts of the text in the buffer. Org -uses just two commands, bound to ‘<TAB>’ and {{{kbd{S-TAB)}}} to change -the visibility in the buffer. - -‘<TAB>’ - _Subtree cycling_: Rotate current subtree among the states - - ,-> FOLDED -> CHILDREN -> SUBTREE --. - '-----------------------------------' - - When called with a prefix argument (‘C-u <TAB>’), or with the Shift - key, global cycling is invoked. - -‘S-<TAB>’ -‘C-u <TAB>’ - _Global cycling_: Rotate the entire buffer among the states - - ,-> OVERVIEW -> CONTENTS -> SHOW ALL --. - '--------------------------------------' - -‘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 - - -File: orgguide.info, Node: Motion, Next: Structure Editing, Prev: Visibility Cycling, Up: Document Structure - -2.3 Motion -========== - -The following commands jump to other headlines in the buffer. - -‘C-c C-n’ - Next heading. - -‘C-c C-p’ - Previous heading. - -‘C-c C-f’ - Next heading same level. - -‘C-c C-b’ - Previous heading same level. - -‘C-c C-u’ - Backward to higher level heading. - - -File: orgguide.info, Node: Structure Editing, Next: Sparse Trees, Prev: Motion, Up: Document Structure - -2.4 Structure Editing -===================== - -‘M-<RET>’ - Insert new heading with same level as current. If point is in a - plain list item, a new item is created (see *note 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(1). - -‘M-S-<RET>’ - Insert new TODO entry with same level as current heading. - -‘<TAB>’ in new -empty entry - In a new entry with no text yet, ‘<TAB>’ cycles through reasonable - levels. - -‘M-<LEFT>’ -‘M-<RIGHT>’ - Promote or demote current heading by one level. - -‘M-<UP>’ -‘M-<DOWN>’ - Move subtree up or down, i.e., swap with previous or next subtree - of same level. - -‘C-c C-w’ - Refile entry or region to a different location. See *note Refile - and Copy::. - -‘C-x n s’ -‘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. - - ---------- Footnotes ---------- - - (1) If you do not want the line to be split, customize the variable -‘org-M-RET-may-split-line’. - - -File: orgguide.info, Node: Sparse Trees, Next: Plain Lists, Prev: Structure Editing, Up: Document Structure - -2.5 Sparse Trees -================ - -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(1). 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: - -‘C-c /’ - This prompts for an extra key to select a sparse-tree creating - command. - -‘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 ‘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. - - ---------- Footnotes ---------- - - (1) See also the variable ‘org-show-context-detail’ to decide how -much context is shown around each match. - - -File: orgguide.info, Node: Plain Lists, Prev: Sparse Trees, Up: Document Structure - -2.6 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 *note Checkboxes::). Org supports editing such lists, -and every exporter (see *note Exporting::) can parse and format them. - - Org knows ordered lists, unordered lists, and description lists. - - • _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: - - * 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. - - The following commands act on items when point is in the first line -of an item (the line with the bullet or number). - -‘<TAB>’ - Items can be folded just like headline levels. - -‘M-<RET>’ - Insert new item at current level. With a prefix argument, force a - new heading (see *note Structure Editing::). - -‘M-S-<RET>’ - Insert a new item with a checkbox (see *note Checkboxes::). - -‘M-S-<UP>’ -‘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. - -‘M-<LEFT>’ -‘M-<RIGHT>’ - Decrease/increase the indentation of an item, leaving children - alone. - -‘M-S-<LEFT>’ -‘M-S-<RIGHT>’ - Decrease/increase the indentation of the item, including subitems. - -‘C-c C-c’ - If there is a checkbox (see *note Checkboxes::) in the item line, - toggle the state of the checkbox. Also verify bullets and - indentation consistency in the whole list. - -‘C-c -’ - Cycle the entire list level through the different itemize/enumerate - bullets (‘-’, ‘+’, ‘*’, ‘1.’, ‘1)’). - - -File: orgguide.info, Node: Tables, Next: Hyperlinks, Prev: Document Structure, Up: Top - -3 Tables -******** - -Org comes with a fast and intuitive table editor. Spreadsheet-like -calculations are supported in connection with the Emacs Calc package -(see *note GNU Emacs Calculator Manual: (calc)Top.). - - 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: - - | Name | Phone | Age | - |-------+-------+-----| - | Peter | 1234 | 17 | - | Anna | 4321 | 25 | - - A table is re-aligned automatically each time you press ‘<TAB>’ or -‘<RET>’ or ‘C-c C-c’ inside the table. ‘<TAB>’ also moves to the next -field (‘<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| - |- - -and then press ‘<TAB>’ to align the table and start filling in fields. -Even faster would be to type ‘|Name|Phone|Age’ followed by ‘C-c <RET>’. - - When typing text into a field, Org treats ‘DEL’, ‘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 ‘<TAB>’, ‘S-<TAB>’ or ‘<RET>’_, the field is -automatically made blank. - -Creation and conversion -======================= - -‘C-c |’ - Convert the active region to table. If every line contains at - least one ‘<TAB>’ character, the function assumes that the material - is tab separated. If every line contains a comma, comma-separated - values (CSV) are assumed. If not, lines are split at whitespace - into fields. - - If there is no active region, this command creates an empty Org - table. But it is easier just to start typing, like ‘| N a m e | P - h o n e | A g e <RET> | - <TAB>’. - -Re-aligning and field motion -============================ - -‘C-c C-c’ - Re-align the table without moving point. - -‘<TAB>’ - Re-align the table, move to the next field. Creates a new row if - necessary. - -‘S-<TAB>’ - Re-align, move to previous field. - -‘<RET>’ - Re-align the table and move down to next row. Creates a new row if - necessary. - -‘S-<UP>’ -‘S-<DOWN>’ -‘S-<LEFT>’ -‘S-<RIGHT>’ - Move a cell up, down, left, and right by swapping with adjacent - cell. - -Column and row editing -====================== - -‘M-<LEFT>’, ‘M-<RIGHT>’ - Move the current column left/right. - -‘M-S-<LEFT>’ - Kill the current column. - -‘M-S-<RIGHT>’ - Insert a new column to the left of point position. - -‘M-<UP>’, ‘M-<DOWN>’ - Move the current row up/down. - -‘M-S-<UP>’ - Kill the current row or horizontal line. - -‘M-S-<DOWN>’ - Insert a new row above the current row. With a prefix argument, - the line is created below the current one. - -‘C-c -’ - Insert a horizontal line below current row. With a prefix - argument, the line is created above the current line. - -‘C-c <RET>’ - Insert a horizontal line below current row, and move the point into - the row below that line. - -‘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. - - -File: orgguide.info, Node: Hyperlinks, Next: TODO Items, Prev: Tables, Up: Top - -4 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: - - [[LINK][DESCRIPTION]] - -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 LINK part, use ‘C-c C-l’ with the point on the -link. - -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 -‘[[#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 -============== - -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 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 -============== - -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 ‘M-x -org-store-link’. Because of its importance, we suggest to bind it to a -widely available key (see *note 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. - -‘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 ‘<UP>’ and - ‘<DOWN>’ to access stored links. You will be prompted for the - description part of the link. - - When called with a ‘C-u’ prefix argument, file name completion is - used to link to a file. - -‘C-c C-l’ (with point on existing link) - When point is on an existing link, ‘C-c C-l’ allows you to edit the - link and description parts of the link. - -‘C-c C-o’ - Open link at point. - -‘C-c &’ - Jump back to a recorded position. A position is recorded by the - commands following internal links, and by ‘C-c %’. Using this - command several times in direct succession moves through a ring of - previously recorded positions. - - -File: orgguide.info, Node: TODO Items, Next: Tags, Prev: Hyperlinks, Up: Top - -5 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. - - -File: orgguide.info, Node: TODO Basics, Next: Multi-state Workflow, Up: TODO Items - -5.1 Basic TODO Functionality -============================ - -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: - -‘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 ‘t’ command key (see *note Agenda Commands::). - -‘S-<RIGHT>’ -‘S-<LEFT>’ - Select the following/preceding TODO state, similar to cycling. - -‘C-c / t’ - View TODO items in a _sparse tree_ (see *note Sparse Trees::). - Folds the entire buffer, but shows all TODO items—with not-DONE - state—and the headings hierarchy above them. - -‘M-x org-agenda t’ - Show the global TODO list. Collects the TODO items (with not-DONE - states) from all agenda files (see *note Agenda Views::) into a - single buffer. See *note Global TODO List::, for more information. - -‘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. - - -File: orgguide.info, Node: Multi-state Workflow, Next: Progress Logging, Prev: TODO Basics, Up: TODO Items - -5.2 Multi-state Workflow -======================== - -You can use TODO keywords to indicate @emph{sequential} working progress -states: - - (setq org-todo-keywords - '((sequence "TODO" "FEEDBACK" "VERIFY" "|" "DONE" "DELEGATED"))) - -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 ‘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: - - (setq org-todo-keywords - '((sequence "TODO(t)" "|" "DONE(d)") - (sequence "REPORT(r)" "BUG(b)" "KNOWNCAUSE(k)" "|" "FIXED(f)"))) - -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 ‘C-c C-t’. - - To define TODO keywords that are valid only in a single file, use the -following text anywhere in the file. - - #+TODO: TODO(t) | DONE(d) - #+TODO: REPORT(r) BUG(b) KNOWNCAUSE(k) | FIXED(f) - #+TODO: | CANCELED(c) - - After changing one of these lines, use ‘C-c C-c’ with the cursor -still in the line to make the changes known to Org mode. - - -File: orgguide.info, Node: Progress Logging, Next: Priorities, Prev: Multi-state Workflow, Up: TODO Items - -5.3 Progress Logging -==================== - -To record a timestamp and a note when changing a TODO state, call the -command ‘org-todo’ with a prefix argument. - -‘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 -*note Clocking Work Time::. - -Closing items -------------- - -The most basic logging is to keep track of _when_ a certain TODO item -was marked as done. This can be achieved with(1) - - (setq org-log-done 'time) - -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(2) - - (setq org-log-done 'note) - -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 ---------------------------- - -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@) - -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’. - - ---------- Footnotes ---------- - - (1) The corresponding in-buffer setting is ‘#+STARTUP: logdone’. - - (2) The corresponding in-buffer setting is ‘#+STARTUP: logenotedone’. - - -File: orgguide.info, Node: Priorities, Next: Breaking Down Tasks, Prev: Progress Logging, Up: TODO Items - -5.4 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 _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. - -‘C-c ,’ - Set the priority of the current headline. Press ‘A’, ‘B’ or ‘C’ to - select a priority, or ‘<SPC>’ to remove the cookie. - -‘S-<UP>’ (‘org-priority-up’) -‘S-<DOWN>’ (‘org-priority-down’) - Increase/decrease the priority of the current headline. - - -File: orgguide.info, Node: Breaking Down Tasks, Next: Checkboxes, Prev: Priorities, Up: TODO Items - -5.5 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 ‘[/]’ or ‘[%]’ anywhere in the headline. These cookies are -updated each time the TODO status of a child changes, or when pressing -‘C-c C-c’ on the cookie. For example: - - * Organize Party [33%] - ** TODO Call people [1/2] - *** TODO Peter - *** DONE Sarah - ** TODO Buy food - ** DONE Talk to neighbor - - -File: orgguide.info, Node: Checkboxes, Prev: Breaking Down Tasks, Up: TODO Items - -5.6 Checkboxes -============== - -Every item in a plain list (see *note 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. - - * TODO Organize party [2/4] - - [-] call people [1/2] - - [ ] Peter - - [X] Sarah - - [X] order food - - 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: - -‘C-c C-c’ - Toggle checkbox status or—with prefix argument—checkbox presence at - point. - -‘M-S-<RET>’ - Insert a new item with a checkbox. This works only if point is - already in a plain list item (see *note Plain Lists::). - - -File: orgguide.info, Node: Tags, Next: Properties, Prev: TODO Items, Up: Top - -6 Tags -****** - -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 -=============== - -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 - - * Meeting with the French group :work: - ** Summary by Frank :boss:notes: - *** TODO Prepare slides for him :action: - -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(1): - - #+FILETAGS: :Peter:Boss:Secret: - -Setting tags -============ - -Tags can simply be typed into the buffer at the end of a headline. -After a colon, ‘M-<TAB>’ offers completion on tags. There is also a -special command for inserting tags: - -‘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. - -‘C-c C-c’ - When point is in a headline, this does the same as ‘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: - - (setq org-tag-alist '(("@work" . ?w) ("@home" . ?h) ("laptop" . ?l))) - - 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 -========== - -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 ] - -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 ‘C-c C-x q’. - -Tag searches -============ - -‘C-c / m’ or ‘C-c \’ - Create a sparse tree with all headlines matching a tags search. - With a ‘C-u’ prefix argument, ignore headlines that are not a TODO - line. - -‘M-x org-agenda m’ - Create a global list of tag matches from all agenda files. See - *note Matching Tags and Properties::. - -‘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 *note Matching Tags and Properties::. - - ---------- Footnotes ---------- - - (1) As with all these in-buffer settings, pressing ‘C-c C-c’ -activates any changes in the line. - - -File: orgguide.info, Node: Properties, Next: Dates and Times, Prev: Tags, Up: Top - -7 Properties -************ - -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: - - * CD collection - ** Classic - *** Goldberg Variations - :PROPERTIES: - :Title: Goldberg Variations - :Composer: J.S. Bach - :Publisher: Deutsche Grammophon - :NDisks: 1 - :END: - - 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: - - * CD collection - :PROPERTIES: - :NDisks_ALL: 1 2 3 4 - :Publisher_ALL: "Deutsche Grammophon" Philips EMI - :END: - - 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: - -‘C-c C-x p’ - Set a property. This prompts for a property name and a value. - -‘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 *note -Tags::). The syntax for the search string is described in *note -Matching Tags and Properties::. - - -File: orgguide.info, Node: Dates and Times, Next: Capture Refile Archive, Prev: Properties, Up: Top - -8 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 _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. - - -File: orgguide.info, Node: Timestamps, Next: Creating Timestamps, Up: Dates and Times - -8.1 Timestamps -============== - -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 [BROKEN -LINK: *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. - - * Meet Peter at the movies - <2006-11-01 Wed 19:15> - * Discussion on climate change - <2006-11-02 Thu 20:00-22:00> - -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: - - * Pick up Sam at school - <2007-05-16 Wed 12:30 +1w> - -Diary-style expression entries - 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: - - * 22:00-23:00 The nerd meeting on every 2nd Thursday of the month - <%%(diary-float t 4 2)> - -Time/Date range - Two timestamps connected by ‘--’ denote a range. - - ** Meeting in Amsterdam - <2004-08-23 Mon>--<2004-08-26 Thu> - -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. - - * Gillian comes late for the fifth time - [2006-11-01 Wed] - - -File: orgguide.info, Node: Creating Timestamps, Next: Deadlines and Scheduling, Prev: Timestamps, Up: Dates and Times - -8.2 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. - -‘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. - -‘C-c !’ - Like ‘C-c .’, but insert an inactive timestamp that does not cause - an agenda entry. - -‘S-<LEFT>’ -‘S-<RIGHT>’ - Change date at point by one day. - -‘S-<UP>’ -‘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. - - -File: orgguide.info, Node: Deadlines and Scheduling, Next: Clocking Work Time, Prev: Creating Timestamps, Up: Dates and Times - -8.3 Deadlines and Scheduling -============================ - -A timestamp may be preceded by special keywords to facilitate planning: - -‘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: - - *** TODO write article about the Earth for the Guide - DEADLINE: <2004-02-29 Sun> - The editor in charge is [[bbdb:Ford Prefect]] - -‘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(1). - - The headline is listed under the given date(2). 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. - - *** TODO Call Trillian for a date on New Years Eve. - SCHEDULED: <2004-12-25 Sat> - - 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: - - ** TODO Pay the rent - DEADLINE: <2005-10-01 Sat +1m> - -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. - - ---------- Footnotes ---------- - - (1) 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. - - (2) 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’. - - -File: orgguide.info, Node: Clocking Work Time, Prev: Deadlines and Scheduling, Up: Dates and Times - -8.4 Clocking Work Time -====================== - -Org mode allows you to clock the time you spend on specific tasks in a -project. - -‘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 - ‘C-u’ prefix argument, select the task from a list of recently - clocked tasks. - -‘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’. - -‘C-c C-x C-e’ - Update the effort estimate for the current clock task. - -‘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. - -‘C-c C-x C-j’ - Jump to the headline of the currently clocked in task. With a - ‘C-u’ prefix argument, select the target task from a list of - recently clocked tasks. - - The ‘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. - - -File: orgguide.info, Node: Capture Refile Archive, Next: Agenda Views, Prev: Dates and Times, Up: Top - -9 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 _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. - -* Menu: - -* Capture:: Capturing new stuff. -* Refile and Copy:: Moving/copying a tree from one place to another. -* Archiving:: What to do with finished products. - - -File: orgguide.info, Node: Capture, Next: Refile and Copy, Up: Capture Refile Archive - -9.1 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. - -Setting up capture ------------------- - -The following customization sets a default target(1) file for notes. - - (setq org-default-notes-file (concat org-directory "/notes.org")) - - You may also define a global key for capturing new material (see -*note Activation::). - -Using capture -------------- - -‘M-x org-capture’ - Start a capture process, placing you into a narrowed indirect - buffer to edit. - -‘C-c C-c’ - Once you have finished entering information into the capture - buffer, ‘C-c C-c’ returns you to the window configuration before - the capture process, so that you can resume your work without - further distraction. - -‘C-c C-w’ - Finalize the capture process by refiling the note to a different - place (see *note Refile and Copy::). - -‘C-c C-k’ - Abort the capture process and return to the previous state. - -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 ‘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: - - (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"))) - - If you then press ‘t’ from the capture menu, Org will prepare the -template for you like this: - - * TODO - [[file:LINK TO WHERE YOU INITIATED CAPTURE]] - -During expansion of the template, special %-escapes(2) 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 ‘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 - - ---------- Footnotes ---------- - - (1) Using capture templates, you get finer control over capture -locations. See *note Capture templates::. - - (2) If you need one of these sequences literally, escape the ‘%’ with -a backslash. - - -File: orgguide.info, Node: Refile and Copy, Next: Archiving, Prev: Capture, Up: Capture Refile Archive - -9.2 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: - -‘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. - -‘C-u C-c C-w’ - Use the refile interface to jump to a heading. - -‘C-u C-u C-c C-w’ - Jump to the location where ‘org-refile’ last moved a tree to. - -‘C-c M-w’ - Copying works like refiling, except that the original note is not - deleted. - - -File: orgguide.info, Node: Archiving, Prev: Refile and Copy, Up: Capture Refile Archive - -9.3 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. - -‘C-c C-x C-a’ - Archive the current entry using the command specified in the - variable ‘org-archive-default-command’. - -‘C-c C-x C-s’ or short ‘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:: - - -File: orgguide.info, Node: Agenda Views, Next: Markup, Prev: Capture Refile Archive, Up: Top - -10 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 _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 *note 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. - - -File: orgguide.info, Node: Agenda Files, Next: Agenda Dispatcher, Up: Agenda Views - -10.1 Agenda Files -================= - -The information to be shown is normally collected from all _agenda -files_, the files listed in the variable ‘org-agenda-files’. - -‘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. - -‘C-c ]’ - Remove current file from the list of agenda files. - -‘C-'’ -‘C-,’ - Cycle through agenda file list, visiting one file after the other. - - -File: orgguide.info, Node: Agenda Dispatcher, Next: Built-in Agenda Views, Prev: Agenda Files, Up: Agenda Views - -10.2 The Agenda Dispatcher -========================== - -The views are created through a dispatcher, accessible with ‘M-x -org-agenda’, or, better, bound to a global key (see *note Activation::). -It displays a menu from which an additional letter is required to -execute a command. The dispatcher offers the following default -commands: - -‘a’ - Create the calendar-like agenda (see [BROKEN LINK: *The - Weekly/daily Agenda]). - -‘t’ -‘T’ - Create a list of all TODO items (see *note Global TODO List::). - -‘m’ -‘M’ - Create a list of headlines matching a given expression (see *note - Matching Tags and Properties::). - -‘s’ - 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. - - -File: orgguide.info, Node: Built-in Agenda Views, Next: Global TODO List, Prev: Agenda Dispatcher, Up: Agenda Views - -10.3 The Weekly/Daily Agenda -============================ - -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. - -‘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: - - * 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 - - Org can interact with Emacs appointments notification facility. To -add the appointments of your agenda files, use the command -‘org-agenda-to-appt’. - - -File: orgguide.info, Node: Global TODO List, Next: Matching Tags and Properties, Prev: Built-in Agenda Views, Up: Agenda Views - -10.4 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 *note Agenda Commands::. - -‘M-x org-agenda t’ - Show the global TODO list. This collects the TODO items from all - agenda files (see *note Agenda Views::) into a single buffer. - -‘M-x org-agenda T’ - Like the above, but allows selection of a specific TODO keyword. - - -File: orgguide.info, Node: Matching Tags and Properties, Next: Search View, Prev: Global TODO List, Up: Agenda Views - -10.5 Matching Tags and Properties -================================= - -If headlines in the agenda files are marked with _tags_ (see *note -Tags::), or have properties (see *note 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 ‘C-c / m’. - -‘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 *note Tags::). If you often need a specific - search, define a custom command for it (see *note Agenda - Dispatcher::). - -‘M-x org-agenda M’ - Like ‘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. - - -File: orgguide.info, Node: Search View, Next: Agenda Commands, Prev: Matching Tags and Properties, Up: Agenda Views - -10.6 Search View -================ - -This agenda view is a general text search facility for Org mode entries. -It is particularly useful to find notes. - -‘M-x org-agenda s’ (‘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’. - - -File: orgguide.info, Node: Agenda Commands, Next: Custom Agenda Views, Prev: Search View, Up: Agenda Views - -10.7 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. - -Motion ------- - -‘n’ - Next line (same as ‘<DOWN>’ and ‘C-n’). - -‘p’ - Previous line (same as ‘<UP>’ and ‘C-p’). - -View/Go to Org file -------------------- - -‘<SPC>’ - Display the original location of the item in another window. With - a prefix argument, make sure that drawers stay folded. - -‘<TAB>’ - Go to the original location of the item in another window. - -‘<RET>’ - Go to the original location of the item and delete other windows. - -Change display --------------- - -‘o’ - Delete other windows. - -‘v d’ or short ‘d’ - Switch to day view. - -‘v w’ or short ‘w’ - Switch to week view. - -‘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. - -‘b’ - Go backward in time to display earlier dates. - -‘.’ - Go to today. - -‘j’ - Prompt for a date and go there. - -‘v l’ or ‘v L’ or short ‘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 ‘C-u’ prefix argument, show all possible - logbook entries, including state changes. - -‘r’ -‘g’ - Recreate the agenda buffer, for example to reflect the changes - after modification of the timestamps of items. - -‘s’ - Save all Org buffers in the current Emacs session, and also the - locations of IDs. - -Remote editing --------------- - -‘0--9’ - Digit argument. - -‘t’ - Change the TODO state of the item, both in the agenda and in the - original Org file. - -‘C-k’ - Delete the current agenda item along with the entire subtree - belonging to it in the original Org file. - -‘C-c C-w’ - Refile the entry at point. - -‘a’ - Archive the subtree corresponding to the entry at point using the - default archiving command set in ‘org-archive-default-command’. - -‘$’ - Archive the subtree corresponding to the current headline. - -‘C-c C-s’ - Schedule this item. With a prefix argument, remove the scheduling - timestamp - -‘C-c C-d’ - Set a deadline for this item. With a prefix argument, remove the - deadline. - -‘S-<RIGHT>’ - Change the timestamp associated with the current line by one day - into the future. - -‘S-<LEFT>’ - Change the timestamp associated with the current line by one day - into the past. - -‘I’ - Start the clock on the current item. - -‘O’ - Stop the previously started clock. - -‘X’ - Cancel the currently running clock. - -‘J’ - Jump to the running clock in another window. - -Quit and exit -------------- - -‘q’ - Quit agenda, remove the agenda buffer. - -‘x’ - Exit agenda, remove the agenda buffer and all buffers loaded by - Emacs for the compilation of the agenda. - - -File: orgguide.info, Node: Custom Agenda Views, Prev: Agenda Commands, Up: Agenda Views - -10.8 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 -‘org-agenda-custom-commands’. You can customize this variable, for -example by pressing ‘C’ from the agenda dispatcher (see *note Agenda -Dispatcher::). You can also directly set it with Emacs Lisp in the -Emacs init file. The following example contains all valid agenda views: - - (setq org-agenda-custom-commands - '(("w" todo "WAITING") - ("u" tags "+boss-urgent") - ("v" tags-todo "+boss-urgent"))) - - 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: - -‘w’ - as a global search for TODO entries with ‘WAITING’ as the TODO - keyword. - -‘u’ - as a global tags search for headlines tagged ‘boss’ but not - ‘urgent’. - -‘v’ - The same search, but limiting it to headlines that are also TODO - items. - - -File: orgguide.info, Node: Markup, Next: Exporting, Prev: Agenda Views, Up: Top - -11 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 *note 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. - - -File: orgguide.info, Node: Paragraphs, Next: Emphasis and Monospace, Up: Markup - -11.1 Paragraphs -=============== - -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_VERSE - Great clouds overhead - Tiny black birds rise and fall - Snow covers Emacs - - ---AlexSchroeder - #+END_VERSE - - 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_QUOTE - Everything should be made as simple as possible, - but not any simpler ---Albert Einstein - #+END_QUOTE - - If you would like to center some text, do it like this: - - #+BEGIN_CENTER - Everything should be made as simple as possible, \\ - but not any simpler - #+END_CENTER - - -File: orgguide.info, Node: Emphasis and Monospace, Next: Embedded LaTeX, Prev: Paragraphs, Up: Markup - -11.2 Emphasis and Monospace -=========================== - -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. - - -File: orgguide.info, Node: Embedded LaTeX, Next: Literal examples, Prev: Emphasis and Monospace, Up: Markup - -11.3 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. - - 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} \]. - - -File: orgguide.info, Node: Literal examples, Next: Images, Prev: Embedded LaTeX, Up: Markup - -11.4 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. - - #+BEGIN_EXAMPLE - Some example from a text file. - #+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: - - Here is an example - : Some example from a text file. - - 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_SRC emacs-lisp - (defun org-xor (a b) - "Exclusive or." - (if a (not b) b)) - #+END_SRC - - To edit the example in a special buffer supporting this language, use -‘C-c '’ to both enter and leave the editing buffer. - - -File: orgguide.info, Node: Images, Next: Creating Footnotes, Prev: Literal examples, Up: Markup - -11.5 Images -=========== - -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 *note Hyperlinks::), make sure that the -link is on a line by itself and precede it with ‘CAPTION’ and ‘NAME’ -keywords as follows: - - #+CAPTION: This is the caption for the next figure link (or table) - #+NAME: fig:SED-HR4049 - [[./img/a.jpg]] - - -File: orgguide.info, Node: Creating Footnotes, Prev: Images, Up: Markup - -11.6 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: - - The Org homepage[fn:1] now looks a lot better than it used to. - ... - [fn:1] The link is: https://orgmode.org - - The following commands handle footnotes: - -‘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. - -‘C-c C-c’ - Jump between definition and reference. - - -File: orgguide.info, Node: Exporting, Next: Publishing, Prev: Markup, Up: Top - -12 Exporting -************ - -Org can convert and export documents to a variety of other formats while -retaining as much structure (see *note Document Structure::) and markup -(see *note 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. - - -File: orgguide.info, Node: The Export Dispatcher, Next: Export Settings, Up: Exporting - -12.1 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. - -‘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. - - -File: orgguide.info, Node: Export Settings, Next: Table of Contents, Prev: The Export Dispatcher, Up: Exporting - -12.2 Export Settings -==================== - -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 -*note The Export Dispatcher::) using the ‘Insert template’ command by -pressing ‘#’. - - -File: orgguide.info, Node: Table of Contents, Next: Include Files, Prev: Export Settings, Up: Exporting - -12.3 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 -‘org-export-with-toc’ variable accordingly. You can achieve the same on -a per file basis, using the following ‘toc’ item in ‘OPTIONS’ keyword: - - #+OPTIONS: toc:2 (only include two levels in TOC) - #+OPTIONS: toc:nil (no default TOC at all) - - Org normally inserts the table of contents directly before the first -headline of the file. - - -File: orgguide.info, Node: Include Files, Next: Comment Lines, Prev: Table of Contents, Up: Exporting - -12.4 Include Files -================== - -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 - -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 ‘C-c '’. - - -File: orgguide.info, Node: Comment Lines, Next: ASCII/UTF-8 Export, Prev: Include Files, Up: Exporting - -12.5 Comment Lines -================== - -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. - -‘C-c ;’ - Toggle the ‘COMMENT’ keyword at the beginning of an entry. - - -File: orgguide.info, Node: ASCII/UTF-8 Export, Next: HTML Export, Prev: Comment Lines, Up: Exporting - -12.6 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. - -‘C-c C-e t a’ -‘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. - - -File: orgguide.info, Node: HTML Export, Next: LaTeX Export, Prev: ASCII/UTF-8 Export, Up: Exporting - -12.7 HTML Export -================ - -Org mode contains an HTML exporter with extensive HTML formatting -compatible with XHTML 1.0 strict standard. - -‘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. ‘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: - - #+HTML: Literal HTML code for export - - #+BEGIN_EXPORT html - All lines between these markers are exported literally - #+END_EXPORT - - -File: orgguide.info, Node: LaTeX Export, Next: iCalendar Export, Prev: HTML Export, Up: Exporting - -12.8 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 _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’. - -‘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. - -‘C-c C-e l p’ - Export as LaTeX file and convert it to PDF file. - -‘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 -*note 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_EXPORT latex - any arbitrary LaTeX code - #+END_EXPORT - - -File: orgguide.info, Node: iCalendar Export, Prev: LaTeX Export, Up: Exporting - -12.9 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. - -‘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’. - -‘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. - - -File: orgguide.info, Node: Publishing, Next: Working with Source Code, Prev: Exporting, Up: Top - -13 Publishing -************* - -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: - - (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\"/>"))) - -‘C-c C-e P x’ - Prompt for a specific project and publish all files that belong to - it. - -‘C-c C-e P p’ - Publish the project containing the current file. - -‘C-c C-e P f’ - Publish only the current file. - -‘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. - - -File: orgguide.info, Node: Working with Source Code, Next: Miscellaneous, Prev: Publishing, Up: Top - -14 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: - - #+NAME: <name> - #+BEGIN_SRC <language> <switches> <header arguments> - <body> - #+END_SRC - -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 ‘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 ‘C-c '’ again to close the buffer and return to the Org -buffer. - -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. - -System-wide header arguments - Those are specified by customizing ‘org-babel-default-header-args’ - variable, or, for a specific language LANG - ‘org-babel-default-header-args:LANG’. - -Header arguments in properties - You can set them using ‘header-args’ property (see *note - Properties::)—or ‘header-args:LANG’ for language 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: - - #+NAME: factorial - #+BEGIN_SRC haskell :results silent :exports code :var n=0 - fac 0 = 1 - fac n = n * fac (n-1) - #+END_SRC - - Code block header arguments can span multiple lines using ‘HEADER’ - keyword on each line. - -Evaluating code blocks -====================== - -Use ‘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_SRC emacs-lisp - (+ 1 2 3 4) - #+END_SRC - - #+RESULTS: - : 10 - - The following syntax is used to pass arguments to code blocks using -the ‘var’ header argument. - - :var NAME=ASSIGN - -NAME is the name of the variable bound in the code block body. 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 -===================== - -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 -===================== - -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 -====================== - -Use ‘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. - - -File: orgguide.info, Node: Miscellaneous, Prev: Working with Source Code, Up: Top - -15 Miscellaneous -**************** - -Completion -========== - -Org has in-buffer completions with ‘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 -=================== - -To quickly insert empty structural blocks, such as ‘#+BEGIN_SRC’ ... -‘#+END_SRC’, or to wrap existing text in such a block, use - -‘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 -========== - -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: - - * 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 - - This kind of view can be achieved dynamically at display time using -Org Indent mode (‘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 ‘<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 - - - -Tag Table: -Node: Top922 -Node: Introduction5668 -Ref: Installation6354 -Ref: Activation7066 -Ref: Feedback7509 -Node: Document Structure7743 -Node: Headlines8814 -Ref: Headlines-Footnote-19696 -Node: Visibility Cycling9819 -Node: Motion11094 -Node: Structure Editing11516 -Ref: Structure Editing-Footnote-112710 -Node: Sparse Trees12814 -Ref: Sparse Trees-Footnote-113882 -Node: Plain Lists13997 -Node: Tables16503 -Ref: Creation and conversion18194 -Ref: Re-aligning and field motion18746 -Ref: Column and row editing19262 -Node: Hyperlinks20267 -Ref: Internal links21025 -Ref: External Links21478 -Ref: Handling Links23308 -Node: TODO Items24697 -Node: TODO Basics25674 -Node: Multi-state Workflow27069 -Node: Progress Logging28865 -Ref: Closing items29612 -Ref: Tracking TODO state changes30167 -Ref: Progress Logging-Footnote-131166 -Ref: Progress Logging-Footnote-231239 -Node: Priorities31317 -Node: Breaking Down Tasks32213 -Node: Checkboxes33016 -Node: Tags34076 -Ref: Tag inheritance34701 -Ref: Setting tags35439 -Ref: Tag groups37159 -Ref: Tag searches37955 -Ref: Tags-Footnote-139047 -Node: Properties39151 -Node: Dates and Times40910 -Node: Timestamps41512 -Node: Creating Timestamps43569 -Node: Deadlines and Scheduling45230 -Ref: Deadlines and Scheduling-Footnote-147254 -Ref: Deadlines and Scheduling-Footnote-247415 -Node: Clocking Work Time47578 -Node: Capture Refile Archive48891 -Node: Capture49699 -Ref: Setting up capture50001 -Ref: Using capture50272 -Ref: Capture templates50867 -Ref: Capture-Footnote-152283 -Ref: Capture-Footnote-252394 -Node: Refile and Copy52485 -Node: Archiving53683 -Node: Agenda Views54995 -Node: Agenda Files56450 -Node: Agenda Dispatcher57110 -Node: Built-in Agenda Views58040 -Node: Global TODO List59129 -Node: Matching Tags and Properties59846 -Node: Search View61815 -Node: Agenda Commands62925 -Ref: Motion (1)63511 -Ref: View/Go to Org file63652 -Ref: Change display63999 -Ref: Remote editing65087 -Ref: Quit and exit66278 -Node: Custom Agenda Views66484 -Node: Markup67960 -Node: Paragraphs68786 -Node: Emphasis and Monospace69908 -Node: Embedded LaTeX70326 -Node: Literal examples71195 -Node: Images72285 -Node: Creating Footnotes72886 -Node: Exporting73807 -Node: The Export Dispatcher74683 -Node: Export Settings75213 -Node: Table of Contents76038 -Node: Include Files76771 -Node: Comment Lines77457 -Node: ASCII/UTF-8 Export78155 -Node: HTML Export78854 -Node: LaTeX Export79862 -Node: iCalendar Export81501 -Node: Publishing82202 -Node: Working with Source Code83804 -Ref: Using header arguments85071 -Ref: Evaluating code blocks86249 -Ref: Results of evaluation87124 -Ref: Exporting code blocks88346 -Ref: Extracting source code88810 -Node: Miscellaneous89337 -Ref: Completion89460 -Ref: Structure Templates89797 -Ref: Clean view90123 - -End Tag Table - - -Local Variables: -coding: utf-8 -End: |