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