mirror of
https://git.savannah.gnu.org/git/emacs.git
synced 2024-12-17 10:06:13 +00:00
2529 lines
90 KiB
Plaintext
2529 lines
90 KiB
Plaintext
\input texinfo
|
|
@c %**start of header
|
|
@c @setfilename org
|
|
@setfilename ../info/org
|
|
@settitle Org Mode Manual
|
|
|
|
@set VERSION 3.13
|
|
@set DATE July 2005
|
|
|
|
@dircategory Emacs
|
|
@direntry
|
|
* Org Mode: (org). Outline-based notes management and organizer
|
|
@end direntry
|
|
|
|
@c Version and Contact Info
|
|
@set MAINTAINERSITE @uref{http://www.astro.uva.nl/~dominik/Tools/org/,maintainers webpage}
|
|
@set MAINTAINER Carsten Dominik
|
|
@set MAINTAINEREMAIL @email{dominik@@science.uva.nl}
|
|
@set MAINTAINERCONTACT @uref{mailto:dominik@@science.uva.nl,contact the maintainer}
|
|
@c %**end of header
|
|
@finalout
|
|
|
|
@c Macro definitions
|
|
|
|
@c Subheadings inside a table. Need a difference between info and the rest.
|
|
@macro tsubheading{text}
|
|
@ifinfo
|
|
@subsubheading \text\
|
|
@end ifinfo
|
|
@ifnotinfo
|
|
@item @b{\text\}
|
|
@end ifnotinfo
|
|
@end macro
|
|
|
|
@copying
|
|
This manual is for Org-mode (version @value{VERSION}).
|
|
|
|
Copyright @copyright{} 2004, 2005 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.1 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 freedom to copy and modify
|
|
this GNU Manual, like GNU software. Copies published by the Free
|
|
Software Foundation raise funds for GNU development.''
|
|
@end quotation
|
|
@end copying
|
|
|
|
@titlepage
|
|
@title Org Mode Manual
|
|
|
|
@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.
|
|
@contents
|
|
|
|
@ifnottex
|
|
@node Top, Introduction, (dir), (dir)
|
|
@top Org Mode Manual
|
|
|
|
@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
|
|
* Timestamps:: Assign date and time to items
|
|
* Timeline and Agenda:: Use time-stamped items to produce an agenda
|
|
* Exporting:: Sharing and publishing of notes
|
|
* Miscellaneous:: All the rest which did not fit elsewhere
|
|
* Index:: The fast road to specific information
|
|
* Key Index:: Key bindings and where they are described
|
|
|
|
@detailmenu
|
|
--- The Detailed Node Listing ---
|
|
|
|
Introduction
|
|
|
|
* Summary:: Brief summary of what Org-mode does
|
|
* Installation and Activation:: How to install Org-mode
|
|
* Feedback:: Bug reportes, ideas, patches etc.
|
|
|
|
Document Structure
|
|
|
|
* Outlines:: Org-mode is based on outline-mode
|
|
* Headlines:: How to typeset org-tree headlines
|
|
* Visibility cycling:: Show ad hide, much simplified
|
|
* Motion:: Jumping to other headlines
|
|
* Structure editing:: Changing sequence and level of headlines
|
|
* Archiving:: Move done task trees to a different place
|
|
* Sparse trees:: Matches embedded in context
|
|
|
|
Tables
|
|
|
|
* Built-in table editor:: Simple tables
|
|
* Table calculations:: Compute a field from other fields
|
|
* orgtbl-mode:: The table editor as minor mode
|
|
* table.el:: Complex tables
|
|
|
|
Calculations in tables
|
|
|
|
* Formula syntax:: How to write a formula
|
|
* Applying a formula:: How to get a formula executed
|
|
* Recalculation:: Re-applying all formulas in a table
|
|
* Summing:: Summing columns and rows
|
|
|
|
Hyperlinks
|
|
|
|
* Links:: URL-like links to the world
|
|
* Remember:: Org-trees store quick notes
|
|
|
|
TODO items
|
|
|
|
* TODO basics:: Marking and displaying TODO entries
|
|
* TODO extensions:: Workflow and assignments
|
|
* Priorities:: Some things are more important than others
|
|
|
|
Extended use of TODO keywords
|
|
|
|
* Workflow states:: From TODO to DONE in steps
|
|
* TODO types:: I do this, Fred the rest
|
|
* Per file keywords:: Different files, different requirements
|
|
|
|
Timestamps
|
|
|
|
* Time stamps:: Assigning a time to a tree entry
|
|
* Creating timestamps:: Commands which insert timestamps
|
|
|
|
Timeline and Agenda
|
|
|
|
* Timeline:: Time-sorted view for single file
|
|
* Agenda:: Your weekly planner
|
|
* Agenda commands:: Remote editing of org trees
|
|
* Calendar/Diary integration:: Integrating Anniversaries and more
|
|
|
|
Calendar/Diary integration
|
|
|
|
* Diary to agenda:: Agenda incorporates the diary
|
|
* Agenda to diary:: Diary incorporates the agenda
|
|
|
|
Exporting
|
|
|
|
* Export commands:: Commands which export and display
|
|
* HTML formatting:: Interpretation of the buffer content
|
|
* Export options:: How to influence exports
|
|
* Comment lines:: Lines which will not be exported
|
|
|
|
Miscellaneous
|
|
|
|
* Completion:: M-TAB knows what you need
|
|
* Customization:: Adapting Org-mode to your taste
|
|
* FAQ:: Frequently asked questions
|
|
* Interaction:: Other Emacs packages
|
|
* Bugs:: Things which do not work perfectly
|
|
* Acknowledgments:: These people provided feedback and more
|
|
|
|
@end detailmenu
|
|
@end menu
|
|
|
|
@node Introduction, Document Structure, Top, Top
|
|
@chapter Introduction
|
|
@cindex introduction
|
|
|
|
@menu
|
|
* Summary:: Brief summary of what Org-mode does
|
|
* Installation and Activation:: How to install Org-mode
|
|
* Feedback:: Bug reportes, ideas, patches etc.
|
|
@end menu
|
|
|
|
@node Summary, Installation and Activation, Introduction, Introduction
|
|
@section Summary
|
|
@cindex summary
|
|
|
|
Org-mode is a mode for keeping notes, maintaining ToDo lists, and doing
|
|
project planning with a fast and effective plain-text system.
|
|
|
|
Org-mode develops organizational tasks around NOTES files that contain
|
|
information about projects as plain text. Org-mode is implemented on
|
|
top of outline-mode, which makes it possible to keep the content of
|
|
large files well structured. Visibility cycling and structure editing
|
|
help to work with the tree. Tables are easily created with a built-in
|
|
table editor. Org-mode supports ToDo items, deadlines, time stamps,
|
|
and scheduling. It dynamically compiles entries into an agenda that
|
|
utilizes and smoothly integrates much of the Emacs calendar and diary.
|
|
Plain text URL-like links connect to websites, emails, usenet
|
|
messages, BBDB entries, and any files related to the projects. For
|
|
printing and sharing of notes, an Org-mode file can be exported as a
|
|
structured ASCII file, or as HTML.
|
|
|
|
Org-mode keeps simple things simple. Not every outline branch needs
|
|
to be an action item, not every action item needs to have priority or
|
|
scheduling information associated with it. Org-mode can be used on
|
|
different levels and in different ways, for example
|
|
|
|
@example
|
|
@r{@bullet{} as an outline extension with visibility cycling and structure editing}
|
|
@r{@bullet{} as an ASCII system and table editor to take structured notes}
|
|
@r{@bullet{} as an ASCII table editor with some spreadsheet-like capabilities}
|
|
@r{@bullet{} as a simple hypertext system, with HTML export}
|
|
@r{@bullet{} as a TODO list editor}
|
|
@r{@bullet{} as a full agenda and planner with deadlines and work scheduling}
|
|
@end example
|
|
|
|
The Org-mode table editor can be integrated into any major mode by
|
|
activating the minor Orgtbl-mode.
|
|
|
|
There is a website for Org-mode which provides links to the newest
|
|
version of Org-mode, as well as additional information, screen shots
|
|
and example files. This page is located at
|
|
@uref{http://www.astro.uva.nl/~dominik/Tools/org/}.
|
|
|
|
@page
|
|
|
|
@node Installation and Activation, Feedback, Summary, Introduction
|
|
@section Installation and Activation
|
|
@cindex installation
|
|
@cindex autoload
|
|
@cindex global keybindings
|
|
@cindex keybindings, global
|
|
|
|
If Org-mode is part of the Emacs distribution or an XEmacs package,
|
|
you only need to copy the following lines to your @file{.emacs} file.
|
|
The last two lines define @emph{global} keys for the commands
|
|
@command{org-store-link} and @command{org-agenda} - please choose
|
|
suitable keys yourself.
|
|
|
|
@lisp
|
|
;; The following lines are always needed. Choose your own keys.
|
|
(add-to-list 'auto-mode-alist '("\\.org$" . org-mode))
|
|
(define-key global-map "\C-cl" 'org-store-link)
|
|
(define-key global-map "\C-ca" 'org-agenda)
|
|
@end lisp
|
|
|
|
If you have downloaded Org-mode from the Web, you must byte-compile
|
|
@file{org.el} and put it on your load path. In addition to the Emacs
|
|
Lisp lines above, you also need to add the following lines to
|
|
@file{.emacs}:
|
|
|
|
@lisp
|
|
;; These lines only if org-mode is not part of the X/Emacs distribution.
|
|
(autoload 'org-mode "org" "Org mode" t)
|
|
(autoload 'org-diary "org" "Diary entries from Org mode")
|
|
(autoload 'org-agenda "org" "Multi-file agenda from Org mode" t)
|
|
(autoload 'org-store-link "org" "Store a link to the current location" t)
|
|
(autoload 'orgtbl-mode "org" "Org tables as a minor mode" t)
|
|
(autoload 'turn-on-orgtbl "org" "Org tables as a minor mode")
|
|
@end lisp
|
|
|
|
@cindex org-mode, turning on
|
|
With this setup, all files with extension @samp{.org} will be put into
|
|
Org-mode. As an alternative, make the first line of a file look like
|
|
this:
|
|
|
|
@example
|
|
MY PROJECTS -*- mode: org; -*-
|
|
@end example
|
|
|
|
@noindent which will select Org-mode for this buffer no matter what
|
|
the file's name is. See also the variable
|
|
@code{org-insert-mode-line-in-empty-file'}.
|
|
|
|
@node Feedback, , Installation and Activation, Introduction
|
|
@section Feedback
|
|
@cindex feedback
|
|
@cindex bug reports
|
|
@cindex maintainer
|
|
@cindex author
|
|
|
|
If you find problems with Org-mode, or if you have questions, remarks,
|
|
or ideas about it, please contact the maintainer Carsten Dominik at
|
|
@value{MAINTAINEREMAIL}.
|
|
|
|
For bug reports, please provide as much information as possible,
|
|
including the version information of Emacs (@kbd{C-h v emacs-version
|
|
@key{RET}}) and Org-mode (@kbd{M-x org-version}), as well as the
|
|
Org-mode related setup in @file{.emacs}. If an error occurs, a
|
|
traceback can be very useful. Often a small example file helps, along
|
|
with clear information about:
|
|
@enumerate
|
|
@item What exactly did you do?
|
|
@item What did you expect to happen?
|
|
@item What happened instead?
|
|
@end enumerate
|
|
@noindent Thanks for helping to improve this mode.
|
|
|
|
@node Document Structure, Tables, Introduction, Top
|
|
@chapter Document Structure
|
|
@cindex document structure
|
|
@cindex structure of document
|
|
|
|
Org-mode is based on outline mode and provides flexible commands to
|
|
edit the structure of the document.
|
|
|
|
@menu
|
|
* Outlines:: Org-mode is based on outline-mode
|
|
* Headlines:: How to typeset org-tree headlines
|
|
* Visibility cycling:: Show ad hide, much simplified
|
|
* Motion:: Jumping to other headlines
|
|
* Structure editing:: Changing sequence and level of headlines
|
|
* Archiving:: Move done task trees to a different place
|
|
* Sparse trees:: Matches embedded in context
|
|
@end menu
|
|
|
|
@node Outlines, Headlines, Document Structure, Document Structure
|
|
@section Outlines
|
|
@cindex outlines
|
|
@cindex outline-mode
|
|
|
|
Org-mode is implemented on top of outline-mode. Outlines allow to
|
|
organize a document in a hierarchical structure, which (at least for
|
|
me) is the best representation of notes and thoughts. Overview over
|
|
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-mode 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
|
|
@cindex headlines
|
|
@cindex outline tree
|
|
|
|
Headlines define the structure of an outline tree. The Headlines in
|
|
Org-mode start with one or more stars, for example
|
|
|
|
@example
|
|
* Top level headline
|
|
** Second level
|
|
*** 3rd level
|
|
some text
|
|
*** 3rd level
|
|
more text
|
|
* Another top level headline
|
|
@end example
|
|
|
|
@node Visibility cycling, Motion, Headlines, Document Structure
|
|
@section Visibility cycling
|
|
@cindex visibility cycling
|
|
@cindex trees, visibility
|
|
|
|
Outlines make it possible to hide parts of the text in the buffer.
|
|
Org-mode uses a single command bound to the @key{TAB} key to change
|
|
the visibility in the buffer.
|
|
|
|
@cindex subtree visibility states
|
|
@cindex folded, subtree visibility state
|
|
@cindex children, subtree visibility state
|
|
@cindex subtree, subtree visibility state
|
|
@table @kbd
|
|
@kindex @key{TAB}
|
|
@item @key{TAB}
|
|
Rotate current subtree between the states
|
|
@example
|
|
,-> FOLDED -> CHILDREN -> SUBTREE --.
|
|
'-----------------------------------'
|
|
@end example
|
|
At the beginning of the buffer (or when called with @kbd{C-u}), this does
|
|
the same as the command @kbd{S-@key{TAB}} below.
|
|
|
|
@cindex global visibility states
|
|
@cindex overview, global visibility state
|
|
@cindex contents, global visibility state
|
|
@cindex show all, global visibility state
|
|
@kindex S-@key{TAB}
|
|
@item S-@key{TAB}
|
|
Rotate the entire buffer between the states
|
|
@example
|
|
,-> OVERVIEW -> CONTENTS -> SHOW ALL --.
|
|
'--------------------------------------'
|
|
@end example
|
|
Note that inside tables, @kbd{S-@key{TAB}} jumps to the previous field.
|
|
|
|
@cindex show all, command
|
|
@kindex C-c C-a
|
|
@item C-c C-a
|
|
Show all.
|
|
@end table
|
|
|
|
When Emacs first visits an Org-mode 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 one of the following lines anywhere in the
|
|
buffer:
|
|
|
|
@example
|
|
#+STARTUP: fold
|
|
#+STARTUP: nofold
|
|
#+STARTUP: content
|
|
@end example
|
|
|
|
@node Motion, Structure editing, Visibility cycling, Document Structure
|
|
@section Motion
|
|
@cindex motion, between headlines
|
|
@cindex jumping, to headlines
|
|
The following commands jump to other headlines in the buffer.
|
|
|
|
@table @kbd
|
|
@kindex C-c C-n
|
|
@item C-c C-n
|
|
Next heading.
|
|
@kindex C-c C-p
|
|
@item C-c C-p
|
|
Previous heading.
|
|
@kindex C-c C-f
|
|
@item C-c C-f
|
|
Next heading same level.
|
|
@kindex C-c C-b
|
|
@item C-c C-b
|
|
Previous heading same level.
|
|
@kindex C-c C-u
|
|
@item C-c C-u
|
|
Backward to higher level heading.
|
|
@kindex C-c C-j
|
|
@item C-c C-j
|
|
Jump to a different place without changing the current outline
|
|
visibility. Shows the document structure in a temporary buffer, where
|
|
you can use visibility cycling (@key{TAB}) to find your destination.
|
|
After pressing @key{RET}, the cursor moves to the selected location in
|
|
the original buffer, and the headings hierarchy above it is made
|
|
visible.
|
|
@end table
|
|
|
|
@node Structure editing, Archiving, Motion, Document Structure
|
|
@section Structure editing
|
|
@cindex structure editing
|
|
@cindex headline, promotion and demotion
|
|
@cindex promotion, of subtrees
|
|
@cindex demotion, of subtrees
|
|
@cindex subtree, cut and paste
|
|
@cindex pasting, of subtrees
|
|
@cindex cutting, of subtrees
|
|
@cindex copying, of subtrees
|
|
|
|
@table @kbd
|
|
@kindex M-@key{RET}
|
|
@item M-@key{RET}
|
|
Insert new heading with same level as current
|
|
@kindex M-S-@key{RET}
|
|
@item M-S-@key{RET}
|
|
Insert new TODO entry with same level as current heading.
|
|
@kindex M-@key{left}
|
|
@item M-@key{left}
|
|
Promote current heading by one level
|
|
@kindex M-@key{right}
|
|
@item M-@key{right}
|
|
Demote current heading by one level
|
|
@kindex M-S-@key{left}
|
|
@item M-S-@key{left}
|
|
Promote the current subtree by one level
|
|
@kindex M-S-@key{right}
|
|
@item M-S-@key{right}
|
|
Demote the current subtree by one level
|
|
@kindex M-S-@key{up}
|
|
@item M-S-@key{up}
|
|
Move subtree up (swap with previous subtree of same level)
|
|
@kindex M-S-@key{down}
|
|
@item M-S-@key{down}
|
|
Move subtree down (swap with next subtree of same level)
|
|
@kindex C-c C-h C-w
|
|
@item C-c C-h C-w
|
|
Kill subtree, i.e. remove it from buffer but save in kill ring.
|
|
@kindex C-c C-h M-w
|
|
@item C-c C-h M-w
|
|
Copy subtree to kill ring.
|
|
@kindex C-c C-h C-y
|
|
@item C-c C-h C-y
|
|
Yank subtree from kill ring. This does modify the level of the subtree to
|
|
make sure the tree fits in nicely at the yank position. The yank
|
|
level can also be specified with a prefix arg, or by yanking after a
|
|
headline marker like @samp{****}.
|
|
@end table
|
|
|
|
@cindex region, active
|
|
@cindex active region
|
|
@cindex transient-mark-mode
|
|
When there is an active region (transient-mark-mode), promotion and
|
|
demotion work on all headlines in the region. To select a region of
|
|
headlines, it is best to place both point and mark at the beginning of a
|
|
line, mark at the beginning of the first headline, and point at the line
|
|
just after the last headline to change. Note that when the cursor is
|
|
inside a table (@pxref{Tables}), the Meta-Cursor keys have different
|
|
functionality.
|
|
|
|
@node Archiving, Sparse trees, Structure editing, Document Structure
|
|
@section Archiving
|
|
@cindex archiving
|
|
|
|
When a project represented by a (sub)tree is finished, you may want
|
|
to move the tree to an archive place, either in the same file under a
|
|
special top-level heading, or even to a different file.
|
|
@table @kbd
|
|
@kindex C-c $
|
|
@item @kbd{C-c $}
|
|
Archive the subtree starting at the cursor position to the location
|
|
given by @code{org-archive-location}.
|
|
@end table
|
|
|
|
@cindex archive locations
|
|
The default archive 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}. If you are also using the Org-mode
|
|
agenda, archiving to a different file is a good way to keep archived
|
|
trees from contributing agenda items.
|
|
|
|
@node Sparse trees, , Archiving, Document Structure
|
|
@section Sparse trees
|
|
@cindex sparse trees
|
|
@cindex trees, sparse
|
|
@cindex folding, sparse trees
|
|
@cindex occur, command
|
|
|
|
An important feature of Org-mode is the ability to construct
|
|
@emph{sparse trees} for selected information in an outline tree. A
|
|
sparse tree means that the entire document is folded as much as
|
|
possible, but the selected information is made visible along with the
|
|
headline structure above it@footnote{See also the variable
|
|
@code{org-show-following-heading}.}. Just try it out and you will see
|
|
immediately how it works.
|
|
|
|
Org-mode contains several commands creating such trees. The most
|
|
basic one is @command{org-occur}:
|
|
|
|
@table @kbd
|
|
@kindex C-c /
|
|
@item C-c /
|
|
Occur. Prompts for a regexp and shows a sparse tree with all matches.
|
|
If the match is in a headline, the headline is made visible. If the
|
|
match is in the body of an entry, headline and body are made visible.
|
|
In order to provide minimal context, also the full hierarchy of
|
|
headlines above the match is shown, as well as the headline following
|
|
the match.
|
|
@end table
|
|
|
|
Other commands are using this feature as well. For example @kbd{C-c
|
|
C-v} creates a sparse TODO tree (@pxref{TODO basics}).
|
|
|
|
@kindex C-c C-x v
|
|
@cindex printing sparse trees
|
|
@cindex visible text, printing
|
|
To print a sparse tree, you can use the Emacs command
|
|
@code{ps-print-buffer-with-faces} which does not print invisible parts
|
|
of the document @footnote{This does not work under XEmacs, because
|
|
XEmacs uses selective display for outlining, not text properties}.
|
|
Or you can use the command @kbd{C-c C-x v} to copy the visible part of
|
|
the document to another file (extension @file{.txt}) which then can be
|
|
printed in any desired way.
|
|
|
|
@node Tables, Hyperlinks, Document Structure, Top
|
|
@chapter Tables
|
|
@cindex tables
|
|
|
|
Org-mode has a very fast and intuitive table editor built-in.
|
|
Spreadsheet-like calculations are supported in connection with the
|
|
Emacs @file{calc} package.
|
|
|
|
@menu
|
|
* Built-in table editor:: Simple tables
|
|
* Table calculations:: Compute a field from other fields
|
|
* orgtbl-mode:: The table editor as minor mode
|
|
* table.el:: Complex tables
|
|
@end menu
|
|
|
|
@node Built-in table editor, Table calculations, Tables, Tables
|
|
@section The built-in table editor
|
|
@cindex table editor, builtin
|
|
|
|
Org-mode makes it easy to format tables in plain ASCII. Any line with
|
|
@samp{|} as the first non-white character is considered part of a
|
|
table. @samp{|} is also the column separator. A table might look
|
|
like this:
|
|
|
|
@example
|
|
| Name | Phone | Age |
|
|
|-------+-------+-----|
|
|
| Peter | 1234 | 17 |
|
|
| Anna | 4321 | 25 |
|
|
@end example
|
|
|
|
A table is re-aligned automatically each time you press @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
|
|
|
|
@example
|
|
|Name|Phone|Age
|
|
|-
|
|
@end example
|
|
|
|
@noindent and then press @key{TAB} to align the table and start filling in
|
|
fields.
|
|
|
|
@table @kbd
|
|
@tsubheading{Creation and conversion}
|
|
@item M-x org-table-create
|
|
Creates an empty Org-mode table. However, it is much easier to just
|
|
start typing, like @kbd{|Name|Phone|Age @key{RET} |- @key{TAB}}
|
|
|
|
@kindex C-c C-c
|
|
@item C-c C-c
|
|
Convert region to table. Works when the cursor is not in an existing
|
|
table, and when there is a region defined. If every line contains at
|
|
least one TAB character, the function assumes that the material is tab
|
|
separated. If not, lines are split at whitespace into fields. You
|
|
can use a prefix argument to indicate how many consecutive spaces are
|
|
at least required to indicate a field separator (default: just one).
|
|
|
|
@tsubheading{Re-aligning and field motion}
|
|
@kindex C-c C-c
|
|
@item C-c C-c
|
|
Re-align the table without moving the cursor.
|
|
|
|
@kindex @key{TAB}
|
|
@item @key{TAB}
|
|
Re-align the table, move to the next field. Creates a new row if
|
|
necessary.
|
|
|
|
@kindex S-@key{TAB}
|
|
@item S-@key{TAB}
|
|
Re-align, move to previous field.
|
|
|
|
@kindex @key{RET}
|
|
@item @key{RET}
|
|
Re-align the table and move down to next row. Creates a new row if
|
|
necessary. At the beginning or end of a line, @key{RET} still does
|
|
NEWLINE, so it can be used to split a table.
|
|
|
|
@tsubheading{Column and row editing}
|
|
@kindex M-@key{left}
|
|
@kindex M-@key{right}
|
|
@item M-@key{left}
|
|
@itemx M-@key{right}
|
|
Move the current column left/right
|
|
|
|
@kindex M-S-@key{left}
|
|
@item M-S-@key{left}
|
|
Kill the current column.
|
|
|
|
@kindex M-S-@key{right}
|
|
@item M-S-@key{right}
|
|
Insert a new column to the left of the cursor position.
|
|
|
|
@kindex M-@key{up}
|
|
@kindex M-@key{down}
|
|
@item M-@key{up}
|
|
@itemx M-@key{down}
|
|
Move the current row up/down
|
|
|
|
@kindex M-S-@key{up}
|
|
@item M-S-@key{up}
|
|
Kill the current row or horizontal line.
|
|
|
|
@kindex M-S-@key{down}
|
|
@item M-S-@key{down}
|
|
Insert a new row above (with arg: below) the current row.
|
|
|
|
@kindex C-c -
|
|
@item C-c -
|
|
Insert a horizontal line below current row. With prefix arg, the line
|
|
is created above the current line.
|
|
|
|
@tsubheading{Regions}
|
|
@kindex C-c C-h M-w
|
|
@item C-c C-h M-w
|
|
Copy a rectangular region from a table to a special clipboard. Point
|
|
and mark determine edge fields of the rectangle. The process ignores
|
|
horizontal separator lines.
|
|
@kindex C-c C-h C-w
|
|
@item C-c C-h C-w
|
|
Copy a rectangular region from a table to a special clipboard, and
|
|
blank all fields in the rectangle. So this is the ``cut'' operation.
|
|
@kindex C-c C-h C-y
|
|
@item C-c C-h C-y
|
|
Paste a rectangular region into a table.
|
|
The upper right corner ends up in the current field. All involved fields
|
|
will be overwritten. If the rectangle does not fit into the present table,
|
|
the table is enlarged as needed. The process ignores horizontal separator
|
|
lines.
|
|
@kindex C-c C-q
|
|
@item C-c C-q
|
|
Wrap several fields in a column like a paragraph. If there is an active
|
|
region, and both point and mark are in the same column, the text in the
|
|
column is wrapped to minimum width for the given number of lines. A
|
|
prefix ARG may be used to change the number of desired lines. If there
|
|
is no region, the current field is split at the cursor position and the
|
|
text fragment to the right of the cursor is prepended to the field one
|
|
line down. If there is no region, but you specify a prefix ARG, the
|
|
current field gets blank, and the content is appended to the field
|
|
above.
|
|
|
|
@tsubheading{Calculations}
|
|
@cindex formula, in tables
|
|
@cindex calculations, in tables
|
|
@kindex C-c =
|
|
@item C-c =
|
|
Replace current field with the result of a formula. When called with a
|
|
@kbd{C-u} prefix, apply the equation in the current field and down
|
|
through the current column to a horizonal separator line or the end of
|
|
the table. For details, see @ref{Table calculations}.
|
|
|
|
@kindex C-c *
|
|
@item C-c *
|
|
Recalculate the current row by applying the stored formulas from left
|
|
to right. When called with a @kbd{C-u} prefix, recalculate the
|
|
entire table, starting with the first non-header line (i.e. below the
|
|
first horizontal separator line). For details, see @ref{Table calculations}.
|
|
|
|
@kindex C-#
|
|
@item C-#
|
|
Rotate the recalculation mark in first column through the states
|
|
@samp{}, @samp{#}, @samp{*}, @samp{!}, @samp{$}. For the meaning of
|
|
these marks see @ref{Table calculations}. When there is an active
|
|
region, change all marks in the region.
|
|
|
|
@kindex C-c ?
|
|
@item C-c ?
|
|
Which table column is the cursor in? Displays number >0 in echo
|
|
area.
|
|
|
|
@cindex region, active
|
|
@cindex active region
|
|
@cindex transient-mark-mode
|
|
@kindex C-c +
|
|
@item C-c +
|
|
Sum the numbers in the current column, or in the rectangle defined by
|
|
the active region. The result is shown in the echo area and can
|
|
be inserted with @kbd{C-y}.
|
|
|
|
@kindex S-@key{RET}
|
|
@item S-@key{RET}
|
|
When current field is empty, copy from first non-empty field above.
|
|
When not empty, copy current field down to next row and move cursor
|
|
along with it. Depending on the variable
|
|
@code{org-table-copy-increment}, integer field values will be
|
|
incremented during copy. This key is also used by CUA-mode
|
|
(@pxref{Interaction}).
|
|
|
|
@tsubheading{Miscellaneous}
|
|
@kindex C-c |
|
|
@item C-c |
|
|
Toggle the visibility of vertical lines in tables. The lines are
|
|
still there, only made invisible with a text property. Any @samp{|}
|
|
added by hand will become invisible on the next align.
|
|
|
|
@item M-x org-table-import
|
|
Import a file as a table. The table should be TAB- or whitespace
|
|
separated. Useful for example to import an Excel table or data from a
|
|
database, because these programs generally can write TAB-separated text
|
|
files. This command works by inserting the file into the buffer and
|
|
then converting the region to a table. Any prefix argument is passed on
|
|
to the converter, which uses it to determine the separator.
|
|
|
|
@item M-x org-table-export
|
|
Export the table as a TAB-separated file. Useful for data exchange with
|
|
for example Excel or database programs.
|
|
|
|
@end table
|
|
|
|
If you don't like the automatic table editor because it gets into your
|
|
way in lines which you would like to start with @samp{|}, you can turn
|
|
it off with
|
|
@lisp
|
|
(setq org-enable-table-editor nil)
|
|
@end lisp
|
|
@noindent The only table command which then still works is
|
|
@kbd{C-c C-c} to do a manual re-align.
|
|
|
|
@node Table calculations, orgtbl-mode, Built-in table editor, Tables
|
|
@section Calculations in tables
|
|
@cindex calculations, in tables
|
|
|
|
While the Org-mode table editor misses many features of a full
|
|
spreadsheet, it nevertheless has very useful capabilities to compute
|
|
fields. In horizontal direction, it can use complex expressions to
|
|
compute a field from other fields @emph{in the same row}, using named
|
|
columns, constants and parameters. The Emacs @file{calc} package is
|
|
required for this feature to work. In vertical direction, only
|
|
summing is supported.
|
|
|
|
@menu
|
|
* Formula syntax:: How to write a formula
|
|
* Applying a formula:: How to get a formula executed
|
|
* Recalculation:: Re-applying all formulas in a table
|
|
* Summing:: Summing columns and rows
|
|
@end menu
|
|
|
|
@node Formula syntax, Applying a formula, Table calculations, Table calculations
|
|
@subsection Formula syntax
|
|
|
|
A formula for horizontal computations can be any algebraic expression
|
|
understood by the Emacs @file{calc} package. Before evaluation,
|
|
variable substitution takes place: @samp{$} is replaced by the field
|
|
the cursor is currently in, and $1..$n reference the fields in the
|
|
current row. @samp{$name} is interpreted as the name of a column,
|
|
parameter or constant. Constants are defined globally through the
|
|
variable @code{org-table-formula-constants}. If you have the
|
|
@file{constants.el} package, it will also be used to resolve
|
|
constants, including natural constants like @samp{$k} for Plancks
|
|
constant, units like @samp{$km} for kilometers. Column names and
|
|
parameters can be specified in special table lines. These are
|
|
described below, see @ref{Recalculation}.
|
|
|
|
A formula can contain an optional mode string after a semicolon. This
|
|
string consists of flags to influence calc's modes@footnote{By
|
|
default, Org-mode uses the standard calc modes (precision 12, angular
|
|
units degrees, fraction and symbolic modes off). However, the display
|
|
format which has been changed to @code{(float 5)} to keep tables
|
|
compact. The default settings can be configured using the variable
|
|
@code{org-calc-default-modes}.} during execution, e.g. @samp{p20} to
|
|
switch the internal precision to 20 digits, @samp{n3}, @samp{s3},
|
|
@samp{e2} or @samp{f4} to switch to normal, scientific, engineering,
|
|
or fix display format, respectively, and @samp{D}, @samp{R}, @samp{F},
|
|
and @samp{S} to turn on degrees, radians, fraction and symbolic modes,
|
|
respectively. In addition, you may provide a @code{printf} specifier
|
|
to reformat the final result. A few examples:
|
|
@example
|
|
$1+$2 @r{Sum of first and second field}
|
|
$1+$2;%.2f @r{Same, format result to two decimals}
|
|
exp($2)+exp($1) @r{Math functions can be used}
|
|
$;%.1f @r{Reformat current cell to 1 decimal}
|
|
($3-32)*5/9 @r{degrees F -> C conversion}
|
|
$c/$1/$cm @r{Hz -> cm conversion, using @file{constants.el}}
|
|
tan($1);Dp3s1 @r{compute in degrees, precision 3, display SCI 1}
|
|
vmean($2..$7) @r{compute column range mean, using vector function}
|
|
taylor($3,x=7,2) @r{taylor series of $3, at x=7, second degree}
|
|
@end example
|
|
|
|
@node Applying a formula, Recalculation, Formula syntax, Table calculations
|
|
@subsection Applying a formula
|
|
|
|
To apply a formula to a field, type it directly into the field,
|
|
preceded by an equal sign, like @samp{=$1+$2}. When you press
|
|
@key{TAB} or @key{RET} or @kbd{C-c C-c} with the cursor still in the
|
|
field, the formula will be evaluated and replaced with the result. If
|
|
the field contains only @samp{=}, the formula most recently applied
|
|
anywhere in the @emph{same column} will be used.
|
|
|
|
For each column, Org-mode will remember the most recently used
|
|
formula. The information is stored in a special line directly below
|
|
the table. When adding/deleting/moving columns with the appropriate
|
|
commands, the stored equations will be modified accordingly. When a
|
|
column used in a calculation is removed, references to this column
|
|
become invalid and will cause an error upon applying the equation.
|
|
|
|
Instead of typing an equation into the field, you may also use the
|
|
command @kbd{C-c =}. It prompts for a formula (with default taken
|
|
from the @samp{#+TBLFM:} line) and applies it to the current field.
|
|
If you use a prefix argument (i.e. @kbd{C-u C-c =}), the formula will
|
|
be applied to the current field and down to the next separator line
|
|
or the end of the table. A numerical prefix will apply it to that
|
|
many fields in the current column.
|
|
|
|
When the evaluation of a formula leads to an error, the field content
|
|
becomes the string @samp{#ERROR}. If you would like see what is going
|
|
on during variable substitution and calculation in order to find a
|
|
bug, turn on formula debugging in the menu and repeat the calculation
|
|
by pressing, for example by pressing @kbd{C-c = @key{RET}} in a field.
|
|
Detailed information will be displayed.
|
|
|
|
@node Recalculation, Summing, Applying a formula, Table calculations
|
|
@subsection Recalculation
|
|
|
|
To recompute all the fields in a line, use the command @kbd{C-c *}.
|
|
It re-applies all stored equations to the current row, from left to
|
|
right. With a @kbd{C-u} prefix, this will be done to every line in
|
|
the table, so use this command it you want to make sure the entire
|
|
table is up-to-date. A more automatic way of recalculating the
|
|
current line requires marking the line: If the first column of a row
|
|
contains only @samp{#}, the row will be re-computed with every
|
|
@key{TAB}, @key{RET}, and @kbd{C-c C-c} in this row. Here is an
|
|
example of a table that collects exam results of students, with some
|
|
rows activated for semi-automatic computations.
|
|
|
|
@example
|
|
@group
|
|
|---+---------+--------+--------+--------+-------+------|
|
|
| | Student | Prob 1 | Prob 2 | Prob 3 | Total | Note |
|
|
|---+---------+--------+--------+--------+-------+------|
|
|
| ! | | P1 | P2 | P3 | Tot | |
|
|
| # | Maximum | 10 | 15 | 25 | 50 | 10.0 |
|
|
| ^ | | m1 | m2 | m3 | mt | |
|
|
|---+---------+--------+--------+--------+-------+------|
|
|
| # | Peter | 10 | 8 | 23 | 41 | 8.2 |
|
|
| # | Sara | 7 | 14 | 19 | 40 | 8.0 |
|
|
| # | Sam | 2 | 4 | 3 | 9 | 1.8 |
|
|
|---+---------+--------+--------+--------+-------+------|
|
|
| $ | max=50 | | | | | |
|
|
|---+---------+--------+--------+--------+-------+------|
|
|
#+TBLFM: $6=vsum($P1..$P3)::$7=10*$Tot/$max;%.1f
|
|
@end group
|
|
@end example
|
|
@noindent
|
|
The example also demonstrates a number of features:
|
|
@enumerate
|
|
@item
|
|
If the first field of a row contains only @samp{!}, this row defines
|
|
@emph{names} for the different columns so that you can write
|
|
@samp{$Tot} instead of @samp{$6} --- useful in larger tables,
|
|
when counting columns becomes error prone.
|
|
@item
|
|
If the first field of a row contains only @samp{$}, fields in this row
|
|
can define @emph{parameters} for formulas. For example, if a field in
|
|
a @samp{$} row contains @samp{max=50}, then formulas in this table can
|
|
refer to the value 50 using @samp{$max}. Parameters work exactly like
|
|
constants, only that they can be defined on a per-table basis.
|
|
Changing a parameter and then recalculating the table can be useful
|
|
and fun.
|
|
@item
|
|
It the first field contains only @samp{^}, fields in this row define
|
|
names for the fields in the row above, for example @samp{$m1} for
|
|
@samp{10}. Similarly, if the marking character is @samp{_}, the names
|
|
are valie for the fields in the row below.
|
|
@item
|
|
A column range @samp{$P1..$P3} is expanded to a vector, so that calc's
|
|
vector functions (in this case @samp{vsum}, but there are many more)
|
|
can be applied to ranges. For a range, columns may be referenced by
|
|
name or number, in either sequence.
|
|
@end enumerate
|
|
|
|
@noindent If a table contains any line with @samp{#} as the
|
|
first field, @kbd{C-u C-c *} will only change the marked lines and
|
|
leave all unmarked lines alone. You can also mark a line with
|
|
@samp{*}. These lines will also be recalculated with @kbd{C-u C-c *},
|
|
but not upon @key{TAB} and @key{RET}. Use this for lines which are
|
|
slow to calculate.
|
|
|
|
Just to wet your appetite on what can be done with the fantastic
|
|
@file{calc} package, here is a table that computes the Taylor series
|
|
for a couple of functions (homework: try that with Excel :-)
|
|
|
|
@example
|
|
@group
|
|
|---+-------------+---+-----+--------------------------------------|
|
|
| | Func | n | x | Result |
|
|
|---+-------------+---+-----+--------------------------------------|
|
|
| # | exp(x) | 1 | x | 1 + x |
|
|
| # | exp(x) | 2 | x | 1 + x + x^2 / 2 |
|
|
| # | exp(x) | 3 | x | 1 + x + x^2 / 2 + x^3 / 6 |
|
|
| # | x^2+sqrt(x) | 2 | x=0 | x*(0.5 / 0) + x^2 (2 - 0.25 / 0) / 2 |
|
|
| # | x^2+sqrt(x) | 2 | x=1 | 2 + 2.5 x - 2.5 + 0.875 (x - 1)^2 |
|
|
| * | tan(x) | 3 | x | 0.0175 x + 1.77e-6 x^3 |
|
|
|---+-------------+---+-----+--------------------------------------|
|
|
#+TBLFM: $5=taylor($2,$4,$3);n3
|
|
@end group
|
|
@end example
|
|
|
|
@node Summing, , Recalculation, Table calculations
|
|
@subsection Summing
|
|
|
|
Finally, when typing a formula into a field, a number of special
|
|
keywords execute predefined sums over the current row or column and
|
|
enter the result into the current field. These calculations are
|
|
one-off, the formula is not stored, and you will neet to re-enter it
|
|
in order to compute again.
|
|
|
|
@example
|
|
= @r{Execute the stored formula valid in this column.}
|
|
=sum @r{Sum all fields above the current (alias @code{=sumv}).}
|
|
=sumh @r{Sum all fields to the left of the current field.}
|
|
=sum3 @r{Same as @samp{=sum}, but use just 3 fields above current.}
|
|
@end example
|
|
|
|
@node orgtbl-mode, table.el, Table calculations, Tables
|
|
@section The Orgtbl minor mode
|
|
@cindex orgtbl-mode
|
|
@cindex minor mode for tables
|
|
|
|
If you like the intuitive way the Org-mode table editor works, you
|
|
might want to use it also in other modes like text-mode or mail-mode.
|
|
The minor mode Orgtbl-mode makes this possible. You can always toggle
|
|
the mode with @kbd{M-x orgtbl-mode}. To turn it on by default, for
|
|
example in mail mode, use
|
|
@lisp
|
|
(add-hook 'mail-mode-hook 'turn-on-orgtbl)
|
|
@end lisp
|
|
|
|
@node table.el, , orgtbl-mode, Tables
|
|
@section The @file{table.el} package
|
|
@kindex C-c C-c
|
|
@cindex table editor, @file{table.el}
|
|
@cindex @file{table.el}
|
|
|
|
Complex ASCII tables with automatic line wrapping, column- and
|
|
row-spanning, and alignment can be created using the Emacs table
|
|
package by Takaaki Ota (@uref{http://sourceforge.net/projects/table}).
|
|
When @key{TAB} or @kbd{C-c C-c} is pressed in such a table, Org-mode
|
|
will call @command{table-recognize-table} and move the cursor into the
|
|
table. Inside a table, the keymap of Org-mode is inactive. In order
|
|
to execute Org-mode-related commands, leave the table.
|
|
|
|
@table @kbd
|
|
@kindex C-c C-c
|
|
@item C-c C-c
|
|
Recognize @file{table.el} table. Works when the cursor is in a
|
|
table.el table.
|
|
|
|
@kindex C-c ~
|
|
@item C-c ~
|
|
Insert a table.el table. If there is already a table at point, this
|
|
command converts it between the table.el format and the Org-mode
|
|
format. See the documentation string of the command
|
|
@code{org-convert-table} for the restrictions under which this is
|
|
possible.
|
|
@end table
|
|
|
|
@node Hyperlinks, TODO items, Tables, Top
|
|
@chapter Hyperlinks
|
|
@cindex hyperlinks
|
|
|
|
Just like HMTL, Org-mode provides links to other files, usenet
|
|
articles, emails and much more.
|
|
|
|
@menu
|
|
* Links:: URL-like links to the world
|
|
* Remember:: Org-trees store quick notes
|
|
@end menu
|
|
|
|
@node Links, Remember, Hyperlinks, Hyperlinks
|
|
@section Links
|
|
@cindex links
|
|
@cindex GNUS links
|
|
@cindex BBDB links
|
|
@cindex URL links
|
|
@cindex file links
|
|
@cindex VM links
|
|
@cindex RMAIL links
|
|
@cindex WANDERLUST links
|
|
@cindex USENET links
|
|
@cindex SHELL links
|
|
|
|
Org-mode supports links to files, websites, usenet and email messages;
|
|
and BBDB database entries. Links are just plain-text URL-like
|
|
locators, optionally enclosed by angular brackets. The following list
|
|
shows examples for each link type.
|
|
|
|
@example
|
|
<http://www.astro.uva.nl/~dominik> @r{on the web}
|
|
<file:/home/dominik/images/jupiter.jpg> @r{file, absolute path}
|
|
<file:papers/last.pdf> @r{file, relative path}
|
|
<file:~/code/main.c:255> @r{file, with line number}
|
|
<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}
|
|
<vm://myself@@some.where.org/folder#id> @r{VM on remote machine}
|
|
<wl:folder> @r{WANDERLUST folder link}
|
|
<wl:folder#id> @r{WANDERLUST message link}
|
|
<rmail:folder> @r{RMAIL folder link}
|
|
<rmail:folder#id> @r{RMAIL message link}
|
|
<gnus:group> @r{GNUS group link}
|
|
<gnus:group#id> @r{GNUS article link}
|
|
<bbdb:Richard Stallman> @r{BBDB link}
|
|
<shell:ls *.org>@footnote{Note that @samp{<} and @samp{>} cannot be part of a link, and therefore of a shell command. If you need redirection, use @@@{ and @@@} instead.} @r{A shell command}
|
|
@end example
|
|
|
|
A link may contain space characters and is terminated by @samp{>} or by
|
|
the end of a line. In tables, the end of a table field also terminates
|
|
a link. Angle brackets around a link are not required, but are
|
|
recommended to avoid problems with punctuation and other text following
|
|
the link. See also the variable @code{org-allow-space-in-links}.
|
|
|
|
@cindex storing links
|
|
@table @kbd
|
|
@kindex C-c l
|
|
@item C-c l
|
|
Store a link to the current location. This is a @emph{global} command
|
|
which can be used in any buffer to create a link. The link will be
|
|
stored for later insertion into an Org-mode buffer (see below). For VM,
|
|
RMAIL, WANDERLUST, GNUS and BBDB buffers, the link will point to the
|
|
current article/entry. For W3 and W3M buffer, the link goes to the
|
|
current URL. For any other files, the link will just point to the file.
|
|
The key binding @kbd{C-c l} is only a suggestion - see
|
|
@ref{Installation and Activation}.
|
|
|
|
@kindex C-c C-l
|
|
@cindex completion, of links
|
|
@cindex completion, of file names
|
|
@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, using one of the link type prefixes
|
|
mentioned in the examples above. Through completion, all links stored
|
|
during the current session can be accessed. When called with prefix
|
|
arg, you can use file name completion to enter a file link. The link
|
|
will be formatted as given in the variable @code{org-link-format} and
|
|
inserted into the buffer. Note that you don't have to use this
|
|
command to insert a link. Links in Org-mode are plain text, and you
|
|
can type or paste them straight into the buffer.
|
|
|
|
@cindex inserting links
|
|
@kindex C-c C-o
|
|
@item C-c C-o
|
|
Open link at point. This will launch a web browser for URLs (using
|
|
@command{browse-url-at-point}), run vm/gnus/bbdb for the corresponding
|
|
links, execute the command in a shell link, visit text files with
|
|
Emacs and select a suitable application for non-text files.
|
|
Classification of files is based on file extension only. See option
|
|
@code{org-file-apps}. If there is no link at point, the current
|
|
subtree will be searched for one. If you want to override the default
|
|
application and visit the file with Emacs, use a @kbd{C-u} prefix.
|
|
If the cursor is on a time stamp, compiles the agenda for that date.
|
|
|
|
@strong{IMPORTANT}: Be careful not to use any dangerous commands in a
|
|
shell link.
|
|
|
|
@kindex mouse-2
|
|
@item mouse-2
|
|
On links, @kbd{mouse-2} will open the link just like @kbd{C-c C-o} would.
|
|
|
|
@kindex mouse-3
|
|
@item mouse-3
|
|
Like @kbd{mouse-2}, but force file links to be opened with Emacs.
|
|
@end table
|
|
|
|
@node Remember, , Links, Hyperlinks
|
|
@section Remember
|
|
@cindex @file{remember.el}
|
|
|
|
Another way to create org entries with links to other files is through
|
|
the @emph{Remember} package by John Wiegley. @emph{Remember} lets you
|
|
store quick notes with little interruption of your work flow. See
|
|
@uref{http://www.emacswiki.org/cgi-bin/wiki/RememberMode} for more
|
|
information. The notes produced by @emph{Remember} can be stored in
|
|
different ways, and Org-mode files are a good target.
|
|
Org-mode allows to file away notes either to a default file, or
|
|
directly to the correct location in your Org-mode outline tree. The
|
|
following customization will tell @emph{Remember} to use org files as
|
|
target, and to create annotations compatible with Org-mode links.
|
|
|
|
@c FIXME: The autoload will not be necessary when Org-mode is part of Emacs
|
|
@example
|
|
(autoload 'org-remember-annotation "org")
|
|
(autoload 'org-remember-handler "org")
|
|
(setq org-directory "~/path/to/my/orgfiles/")
|
|
(setq org-default-notes-file "~/.notes")
|
|
(setq remember-annotation-functions '(org-remember-annotation))
|
|
(setq remember-handler-functions '(org-remember-handler))
|
|
@end example
|
|
|
|
When you compose a note with remember, you have to press @kbd{C-c C-c}
|
|
to exit remember-mode and to file away the note. The handler first
|
|
prompts for a target file - if you press @key{RET}, the value of
|
|
@code{org-default-notes-file} is used. Then the command offers the
|
|
headings tree of the selected file. You can either immediately press
|
|
@key{RET} to get the note appended to the file. Or you can use
|
|
vertical cursor motion (@key{up} and @key{down}) and visibility
|
|
cycling (@key{TAB}) to find a better place. Pressing @key{RET} or
|
|
@key{left} or @key{right} leads to the following result.
|
|
|
|
@multitable @columnfractions 0.2 0.1 0.7
|
|
@item @b{Cursor position} @tab @b{Key} @tab @b{Note gets inserted}
|
|
@item buffer-start @tab @key{RET} @tab as level 2 heading at end of file
|
|
@item on headline @tab @key{RET} @tab as sublevel of the heading at cursor
|
|
@item @tab @key{left} @tab as same level, before current heading
|
|
@item @tab @key{right} @tab as same level, after current heading
|
|
@item not on headline @tab @key{RET}
|
|
@tab at cursor position, level taken from context.
|
|
Or use prefix arg to specify level manually.
|
|
@end multitable
|
|
|
|
So a fast way to store the note is to press @kbd{C-c C-c @key{RET}
|
|
@key{RET}} to append it to the default file. Even shorter would be
|
|
@kbd{C-u C-c C-c}, which does the same without even showing the tree.
|
|
But with little extra effort, you can push it directly to the correct
|
|
location.
|
|
|
|
Before inserting the text into a tree, the function ensures that the
|
|
text has a headline, i.e. a first line that starts with a @samp{*}.
|
|
If not, a headline is constructed from the current date and some
|
|
additional data. If the variable @code{org-adapt-indentation} is
|
|
non-nil, the entire text is also indented so that it starts in the
|
|
same column as the headline (after the asterisks).
|
|
|
|
@node TODO items, Timestamps, Hyperlinks, Top
|
|
@chapter TODO items
|
|
@cindex TODO items
|
|
|
|
Org-mode does not maintain TODO lists as a separate document. TODO
|
|
items are an integral part of the notes file, because TODO items
|
|
usually come up while taking notes! With Org-mode, you simply mark
|
|
any entry in a tree as being a TODO item. In this way, the
|
|
information is not duplicated, and the entire context from which the
|
|
item emerged is always present when you check.
|
|
|
|
Of course, this technique causes TODO items to be scattered throughout
|
|
your file. Org-mode provides methods to give you an overview over all
|
|
things you have to do.
|
|
|
|
@menu
|
|
* TODO basics:: Marking and displaying TODO entries
|
|
* TODO extensions:: Workflow and assignments
|
|
* Priorities:: Some things are more important than others
|
|
@end menu
|
|
|
|
@node TODO basics, TODO extensions, TODO items, TODO items
|
|
@section Basic TODO functionality
|
|
|
|
Any headline can become a TODO item by starting it with the word TODO,
|
|
for example
|
|
|
|
@example
|
|
*** TODO Write letter to Sam Fortune
|
|
@end example
|
|
|
|
@noindent
|
|
The most important commands to work with TODO entries are:
|
|
|
|
@table @kbd
|
|
@kindex C-c C-t
|
|
@item C-c C-t
|
|
Rotate the TODO state of the current item between
|
|
@example
|
|
,-> (unmarked) -> TODO -> DONE --.
|
|
'--------------------------------'
|
|
@end example
|
|
The same rotation can also be done ``remotely'' from the timeline and
|
|
agenda buffers with the @kbd{t} command key (@pxref{Agenda commands}).
|
|
@kindex C-c C-v
|
|
@cindex sparse tree, for TODO
|
|
@item C-c C-v
|
|
View TODO items in a @emph{sparse tree} (@pxref{Sparse trees}). Folds
|
|
the entire buffer, but shows all TODO items and the headings hierarchy
|
|
above them. With prefix arg, show also the DONE entries.
|
|
@item C-u C-c a
|
|
A @kbd{C-u} argument to the @code{org-agenda command} (@pxref{Agenda})
|
|
collects all unfinished TODO items into a single place.
|
|
@end table
|
|
|
|
@node TODO extensions, Priorities, TODO basics, TODO items
|
|
@section Extended use of TODO keywords
|
|
@cindex extended TODO keywords
|
|
|
|
The default implementation of TODO entries is just two states: TODO
|
|
and DONE. You can, however, use the TODO feature for more
|
|
complicated things by configuring the variables
|
|
@code{org-todo-keywords} and @code{org-todo-interpretation}. Using
|
|
special setup, you can even use TODO keywords in different ways in
|
|
different org files.
|
|
|
|
@menu
|
|
* Workflow states:: From TODO to DONE in steps
|
|
* TODO types:: I do this, Fred the rest
|
|
* Per file keywords:: Different files, different requirements
|
|
@end menu
|
|
|
|
@node Workflow states, TODO types, TODO extensions, TODO extensions
|
|
@subsection TODO keywords as workflow states
|
|
@cindex TODO workflow
|
|
@cindex workflow states as TODO keywords
|
|
|
|
You can use TODO keywords to indicate different states in the process
|
|
of working on an item, for example
|
|
|
|
@lisp
|
|
(setq org-todo-keywords '("TODO" "FEEDBACK" "VERIFY" "DONE")
|
|
org-todo-interpretation 'sequence)
|
|
@end lisp
|
|
|
|
@cindex completion, of TODO keywords
|
|
With this setup, the command @kbd{C-c C-t} will cycle an entry from
|
|
TODO to FEEDBACK, then to VERIFY, and finally too DONE. You may also
|
|
use a prefix argument to quickly select a specific state. For example
|
|
@kbd{C-3 C-c C-t} will change the state immediately to VERIFY.
|
|
If you define many keywords, you can use in-buffer completion (see
|
|
@ref{Completion}) to insert these words into the buffer.
|
|
|
|
@node TODO types, Per file keywords, Workflow states, TODO extensions
|
|
@subsection TODO keywords as types
|
|
@cindex TODO types
|
|
@cindex names as TODO keywords
|
|
@cindex types as TODO keywords
|
|
|
|
The second possibility is to use TODO keywords to indicate different
|
|
types of action items. For example, you might want to indicate that
|
|
items are for ``work'' or ``home''. Or, when you work with several
|
|
people on a single project, you might want to assign action items
|
|
directly to persons, by using their names as TODO keywords. This
|
|
would be set up like this:
|
|
|
|
@lisp
|
|
(setq org-todo-keywords '("Fred" "Sara" "Lucy" "Mike" "DONE")
|
|
org-todo-interpretation 'type)
|
|
@end lisp
|
|
|
|
In this case, different keywords do not indicate a sequence, but
|
|
rather different types. So it is normally not useful to change from
|
|
one type to another. Therefore, in this case the behavior of the
|
|
command @kbd{C-c C-t} is changed slightly@footnote{This is also true
|
|
for the @kbd{t} command in the timeline and agenda buffers.}. When
|
|
used several times in succession, it will still cycle through all
|
|
names. But when when you return to the item after some time and
|
|
execute @kbd{C-c C-t} again, it will switch from each name directly to
|
|
DONE. Use prefix arguments or completion to quickly select a specific
|
|
name.
|
|
|
|
@node Per file keywords, , TODO types, TODO extensions
|
|
@subsection Setting up TODO keywords for individual files
|
|
@cindex keyword options
|
|
@cindex per file keywords
|
|
|
|
It can be very useful to use different aspects of the TODO mechanism
|
|
in different files, which is not possible with the global settings
|
|
described above. For file-local settings, you need to add special
|
|
lines to the file which set the keywords and interpretation for that
|
|
file only. For example, to set one of the two examples discussed
|
|
above, you need one of the following lines, starting in column zero
|
|
anywhere in the file:
|
|
|
|
@example
|
|
#+SEQ_TODO: TODO FEEDBACK VERIFY DONE
|
|
#+TYP_TODO: Fred Sara Lucy Mike DONE
|
|
@end example
|
|
|
|
@cindex Completion, of option keywords
|
|
@kindex M-@key{TAB}
|
|
@noindent To make sure you are using the correct keyword, type
|
|
@samp{#+} into the buffer and then use @kbd{M-@key{TAB}} completion.
|
|
|
|
@cindex DONE, final TODO keyword
|
|
Remember that the last keyword must always mean that the item is DONE
|
|
(you may use a different word, though). Also note that in each file,
|
|
only one of the two aspects of TODO keywords can be used. 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@footnote{Org-mode
|
|
parses these lines only when Org-mode is activated after visiting a
|
|
file. @kbd{C-c C-c} with the cursor in a line starting with @samp{#-}
|
|
is simply restarting Org-mode, making sure that these changes will be
|
|
respected.}.
|
|
|
|
If you want to use very many keywords, for example when working with a
|
|
large group of people, you may split the names over several lines:
|
|
|
|
@example
|
|
#+TYP_TODO: Fred Sara Lucy Mike
|
|
#+TYP_TODO: Luis George Jules Jessica
|
|
#+TYP_TODO: Kim Arnold Peter
|
|
#+TYP_TODO: DONE
|
|
@end example
|
|
|
|
@node Priorities, , TODO extensions, TODO items
|
|
@section Priorities
|
|
@cindex priorities
|
|
|
|
If you use Org-mode extensively to organize your work, you may end up
|
|
with a number of TODO entries so large that you'd like to prioritize
|
|
them. This can be done by placing a @emph{priority cookie} into the
|
|
headline, like this
|
|
|
|
@example
|
|
*** TODO [#A] Write letter to Sam Fortune
|
|
@end example
|
|
|
|
@noindent
|
|
With its standard setup, Org-mode supports priorities @samp{A},
|
|
@samp{B}, and @samp{C}. @samp{A} is the highest priority. An entry
|
|
without a cookie is treated as priority @samp{B}. Priorities make a
|
|
difference only in the agenda (@pxref{Agenda}).
|
|
|
|
@table @kbd
|
|
@kindex @kbd{C-c ,}
|
|
@item @kbd{C-c ,}
|
|
Set the priority of the current item. The command prompts for a
|
|
priority character @samp{A}, @samp{B} or @samp{C}. When you press
|
|
@key{SPC} instead, the priority cookie is removed from the headline.
|
|
The priorities can also be changed ``remotely'' from the timeline and
|
|
agenda buffer with the @kbd{,} command (@pxref{Agenda commands}).
|
|
|
|
@kindex S-@key{up}
|
|
@kindex S-@key{down}
|
|
@item S-@key{up}
|
|
@itemx S-@key{down}
|
|
Increase/decrease priority of current item. Note that these keys are
|
|
also used to modify time stamps (@pxref{Creating timestamps}).
|
|
Furthermore, these keys are also used by CUA-mode
|
|
(@pxref{Interaction}).
|
|
@end table
|
|
|
|
|
|
|
|
@node Timestamps, Timeline and Agenda, TODO items, Top
|
|
@chapter Timestamps
|
|
|
|
Items can be labeled with timestamps to make them useful for project
|
|
planning.
|
|
|
|
@menu
|
|
* Time stamps:: Assigning a time to a tree entry
|
|
* Creating timestamps:: Commands which insert timestamps
|
|
@end menu
|
|
|
|
|
|
@node Time stamps, Creating timestamps, Timestamps, Timestamps
|
|
@section Time stamps, deadlines and scheduling
|
|
@cindex time stamps
|
|
@cindex deadlines
|
|
@cindex scheduling
|
|
|
|
A time stamp is a specification of a date (possibly with time) in a
|
|
special format, either @samp{<2003-09-16 Tue>} or @samp{<2003-09-16
|
|
Tue 09:39>}. A time stamp can appear anywhere in the headline or body
|
|
of an org-tree entry. Its presence allows to show entries on specific
|
|
dates in the agenda (@pxref{Agenda}). We distinguish:
|
|
|
|
@table @var
|
|
@cindex timestamp
|
|
@item TIMESTAMP
|
|
A simple time stamp just assigns a date/time to an item. In the
|
|
timeline and agenda displays, the headline of the entry will be shown
|
|
exactly on that date.
|
|
|
|
@item TIMERANGE
|
|
@cindex timerange
|
|
Two time stamps connected by @samp{--} denote a time range. The
|
|
headline will be shown on the first and last day of the range, and on
|
|
any dates that are displayed and fall in the range. Here is an
|
|
example:
|
|
|
|
@example
|
|
** Meeting in Amsterdam
|
|
<2004-08-23 Mon>--<2004-08-26 Thu>
|
|
@end example
|
|
|
|
@item DEADLINE
|
|
@cindex DEADLINE keyword
|
|
If a time stamp is preceded by the word @samp{DEADLINE:}, the task
|
|
(most likely a TODO item) is supposed to be finished on that date, and
|
|
it will be listed then. In addition, the compilation 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:
|
|
|
|
@example
|
|
*** TODO write article about the Earth for the Guide
|
|
The editor in charge is <bbdb:Ford Prefect>
|
|
DEADLINE: <2004-02-29 Sun>
|
|
@end example
|
|
|
|
@item SCHEDULED
|
|
@cindex DEADLINE keyword
|
|
If a time stamp is preceded by the word @samp{SCHEDULED:}, it means
|
|
you are planning to start working on that task on the given date. The
|
|
headline will be listed under the given date. 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.
|
|
@end table
|
|
|
|
@node Creating timestamps, , Time stamps, Timestamps
|
|
@section Creating timestamps
|
|
@cindex creating timestamps
|
|
|
|
For Org-mode to recognize time stamps, they need to be in the specific
|
|
format. All commands listed below produce time stamps in the correct
|
|
format.
|
|
|
|
@table @kbd
|
|
@kindex C-c .
|
|
@item C-c .
|
|
Prompt for a date and insert a corresponding time stamp. When the
|
|
cursor is at a previously used time stamp, it is updated to NOW. When
|
|
this command is used twice in succession, a time range is inserted.
|
|
|
|
@kindex C-u C-c .
|
|
@item C-u C-c .
|
|
Like @kbd{C-c .}, but use the alternative format which contains date
|
|
and time.
|
|
|
|
@kindex C-c <
|
|
@item C-c <
|
|
Insert a time stamp corresponding to the cursor date in the Calendar.
|
|
|
|
@kindex C-c >
|
|
@item C-c >
|
|
Access the Emacs calendar for the current date. If there is a
|
|
timestamp in the current line, goto the corresponding date
|
|
instead.
|
|
|
|
@kindex C-c C-o
|
|
@item C-c C-o
|
|
Access the agenda for the date given by the time stamp at point
|
|
(@pxref{Agenda}).
|
|
|
|
@kindex C-c C-d
|
|
@item C-c C-d
|
|
Insert @samp{DEADLINE} keyword along with a stamp.
|
|
@kindex C-c C-w
|
|
@cindex sparse tree, for deadlines
|
|
@item C-c C-w
|
|
Create a sparse tree with all deadlines that are either past-due, or
|
|
which will become due within @code{org-deadline-warning-days}.
|
|
With @kbd{C-u} prefix, show all deadlines in the file. With a numeric
|
|
prefix, check that many days. For example, @kbd{C-1 C-c C-w} shows
|
|
all deadlines due tomorrow.
|
|
|
|
@kindex C-c C-s
|
|
@item C-c C-s
|
|
Insert @samp{SCHEDULED} keyword along with a stamp.
|
|
|
|
@kindex S-@key{left}
|
|
@kindex S-@key{right}
|
|
@item S-@key{left}
|
|
@itemx S-@key{right}
|
|
Change date at cursor by one day. These key bindings conflict with
|
|
CUA-mode (@pxref{Interaction}).
|
|
|
|
@kindex S-@key{up}
|
|
@kindex S-@key{down}
|
|
@item S-@key{up}
|
|
@itemx S-@key{down}
|
|
Change the item under the cursor in a timestamp. The cursor can be on
|
|
a year, month, day, hour or minute. Note that if the cursor is not at
|
|
a time stamp, these same keys modify the priority of an item.
|
|
(@pxref{Priorities}). The key bindings also conflict with CUA-mode
|
|
(@pxref{Interaction}).
|
|
|
|
|
|
@kindex C-c C-y
|
|
@cindex evaluate time range
|
|
@item C-c C-y
|
|
Evaluate a time range by computing the difference between start and
|
|
end. With prefix arg, insert result after the time range (in a table:
|
|
into the following column).
|
|
@end table
|
|
|
|
@cindex date, reading in minibuffer
|
|
@cindex time, reading in minibuffer
|
|
@cindex calendar, for selecting date
|
|
When Org-mode prompts for a date/time, the function reading your input
|
|
will replace anything you choose not to specify with the current date
|
|
and time. For details, see the documentation string of
|
|
@command{org-read-date}. Also, a calender will pop up to allow
|
|
selecting a date. The calendar can be fully controlled from the
|
|
minibuffer, and a date can be selected with the following commands:
|
|
|
|
@table @kbd
|
|
@kindex <
|
|
@item <
|
|
Scroll calendar backwards by one month.
|
|
@kindex >
|
|
@item >
|
|
Scroll calendar forwards by one month.
|
|
@kindex mouse-1
|
|
@item mouse-1
|
|
Select date by clicking on it.
|
|
@kindex S-@key{right}
|
|
@item S-@key{right}
|
|
One day forward.
|
|
@kindex S-@key{left}
|
|
@item S-@key{left}
|
|
One day back.
|
|
@kindex S-@key{down}
|
|
@item S-@key{down}
|
|
One week forward.
|
|
@kindex S-@key{up}
|
|
@item S-@key{up}
|
|
One week back.
|
|
@kindex M-S-@key{right}
|
|
@item M-S-@key{right}
|
|
One month forward.
|
|
@kindex M-S-@key{left}
|
|
@item M-S-@key{left}
|
|
One month back.
|
|
@kindex @key{RET}
|
|
@item @key{RET}
|
|
Choose date in calendar (only if nothing typed into minibuffer).
|
|
@end table
|
|
|
|
@node Timeline and Agenda, Exporting, Timestamps, Top
|
|
@chapter Timeline and Agenda
|
|
@cindex agenda
|
|
|
|
We have already described three commands to filter important
|
|
information in an org file into a sparse tree (@pxref{Sparse trees}):
|
|
|
|
@cindex sparse trees
|
|
@itemize @bullet
|
|
@item
|
|
The TODO tree, (@kbd{C-c C-v}), see @ref{TODO items}.
|
|
@item
|
|
The occur tree @kbd{C-c /}, see @ref{TODO items}.
|
|
@item
|
|
Checking upcoming deadlines with @kbd{C-c C-w}, see @ref{Creating
|
|
timestamps}.
|
|
@end itemize
|
|
@noindent
|
|
|
|
Instead of using the sparse trees, Org-mode can also collect and
|
|
time-sort the important items into a separate buffer, which we call
|
|
the @emph{timeline} of the org file. It can also collect information
|
|
from a @emph{list of files} and in this way provide an @emph{agenda}
|
|
which covers all of your current projects, action items and
|
|
appointments.
|
|
|
|
@menu
|
|
* Timeline:: Time-sorted view for single file
|
|
* Agenda:: Your weekly planner
|
|
* Agenda commands:: Remote editing of org trees
|
|
* Calendar/Diary integration:: Integrating Anniversaries and more
|
|
@end menu
|
|
|
|
@node Timeline, Agenda, Timeline and Agenda, Timeline and Agenda
|
|
@section Timeline for a single file
|
|
@cindex single file summary
|
|
@cindex agenda, for single file
|
|
@cindex timeline, single file
|
|
@cindex time-sorted view
|
|
|
|
The timeline shows all time-stamped items in a single Org-mode file,
|
|
in @emph{time-sorted view}. The main purpose of this command is to
|
|
give an overview over events in a project.
|
|
|
|
@table @kbd
|
|
@kindex C-c C-r
|
|
@item C-c C-r
|
|
Show a time-sorted view of the org file, with all time-stamped items
|
|
of today or later. When called with a @kbd{C-u} prefix, past dates
|
|
will be included as well. When called with two @kbd{C-u C-u}
|
|
prefixes, all unfinished TODO entries (scheduled or not) are also
|
|
listed under the current date.
|
|
@end table
|
|
@noindent
|
|
|
|
The timeline is shown in a temporary buffer @file{*Org Agenda*}. The
|
|
commands available in the Agenda buffer are listed in @ref{Agenda
|
|
commands}.
|
|
|
|
@node Agenda, Agenda commands, Timeline, Timeline and Agenda
|
|
@section Agenda
|
|
@cindex agenda
|
|
|
|
An agenda can be compiled from one or more org files. The main
|
|
purpose of this command is to act like a paper agenda, showing you all
|
|
the tasks for the current day or week.
|
|
|
|
The Org-mode files to be processed in order to generate the agenda are
|
|
listed in the variable @code{org-agenda-files}. You can customize
|
|
this variable, but the easiest way to maintain it is through the
|
|
following commands
|
|
|
|
@cindex files, adding to agenda list
|
|
@table @kbd
|
|
@kindex C-c [
|
|
@item C-c [
|
|
Add current file to the list of agenda files
|
|
@kindex C-c ]
|
|
@item C-c ]
|
|
Remove current file from the list of agenda files.
|
|
@end table
|
|
@noindent
|
|
The Org menu contains the list of all files and can be used to quickly
|
|
visit any of them.
|
|
|
|
The global command @command{org-agenda} compiles the agenda from all
|
|
listed files.
|
|
|
|
@table @kbd
|
|
@cindex org-agenda, command
|
|
@kindex C-c a
|
|
@item C-c a
|
|
Compile an agenda for the current week from a list of org files. The
|
|
agenda shows the entries for each day. With a @kbd{C-u} prefix (or
|
|
when the variable @code{org-agenda-include-all-todo} is @code{t}), all
|
|
unfinished TODO items (also those without a date) are also listed at
|
|
the beginning of the buffer, before the first date.@*
|
|
The key binding @kbd{C-c a} is only a suggestion - see
|
|
@ref{Installation and Activation}.
|
|
@end table
|
|
|
|
The commands available in the Agenda buffer are listed in
|
|
@ref{Agenda commands}.
|
|
|
|
@subsection Categories
|
|
|
|
@cindex category
|
|
In the agenda buffer, each entry is preceded by a @emph{category},
|
|
which is derived from the file name. The category can also be set
|
|
with a special line anywhere in the buffer, looking like this:
|
|
@example
|
|
#+CATEGORY: Thesis
|
|
@end example
|
|
@noindent
|
|
After changing this line, press @kbd{C-c C-c} with the cursor still in
|
|
the line, to make the changes known to org-mode. Otherwise, the
|
|
change will only be active the next time you visit this file with
|
|
Emacs.
|
|
|
|
The display in the agenda buffer looks best if the category is not
|
|
longer than 10 characters.
|
|
|
|
@subsection Time-of-Day Specifications
|
|
|
|
Org-mode checks each agenda item for a time-of-day specification. The
|
|
time can be part of the time stamp that triggered inclusion into the
|
|
agenda, for example as in @w{@samp{<2005-05-10 Tue 19:00>}}. Time
|
|
ranges can be specified with two time stamps, like
|
|
@c
|
|
@w{@samp{<2005-05-10 Tue 20:30>--<2005-05-10 Tue 22:15>}}.
|
|
|
|
In the headline of the entry itself, a time(range) may also appear as
|
|
plain text (like @samp{12:45} or a @samp{8:30-1pm}. If the agenda
|
|
integrates the Emacs diary (@pxref{Calendar/Diary integration}), time
|
|
specifications in diary entries are recognized as well.
|
|
|
|
For agenda display, Org-mode extracts the time and displays it in a
|
|
standard 24 hour format as part of the prefix. The example times in
|
|
the previous paragraphs would end up in the agenda like this:
|
|
|
|
@example
|
|
8:30-13:00 Arthur Dent lies in front of the bulldozer
|
|
12:45...... Ford Prefect arrives and takes Arthur to the pub
|
|
19:00...... The Vogon reads his poem
|
|
20:30-22:15 Marwin escorts the Hitchhikers to the bridge
|
|
@end example
|
|
|
|
If the agenda is in single-day mode, or for the display of today, the
|
|
timed entries are embedded in a time grid, like
|
|
|
|
@example
|
|
8:00...... ------------------
|
|
8:30-13:00 Arthur Dent lies in front of the bulldozer
|
|
10:00...... ------------------
|
|
12:00...... ------------------
|
|
12:45...... Ford Prefect arrives and takes Arthur to the pub
|
|
14:00...... ------------------
|
|
16:00...... ------------------
|
|
18:00...... ------------------
|
|
19:00...... The Vogon reads his poem
|
|
20:00...... ------------------
|
|
20:30-22:15 Marwin escorts the Hitchhikers to the bridge
|
|
@end example
|
|
|
|
The time grid can be turned on and off with the variable
|
|
@code{org-agenda-use-time-grid}, and can be configured with
|
|
@code{org-agenda-time-grid}.
|
|
|
|
|
|
@subsection Sorting of agenda items
|
|
@cindex sorting, of agenda items
|
|
@cindex priorities, of agenda items
|
|
The entries for each day are sorted. The default order is to first
|
|
collect all items containing an explicit time-of-day specification.
|
|
These entries will be shown at the beginning of the list, as a
|
|
@emph{schedule} for the day. After that, items remain grouped in
|
|
categories, in the sequence given by @code{org-agenda-files}. Within
|
|
each category, items are sorted by priority (@pxref{Priorities}).
|
|
|
|
The priority is a numerical quantity composed of the base priority
|
|
(2000 for priority @samp{A}, 1000 for @samp{B}, and 0 for @samp{C}),
|
|
plus additional increments for overdue scheduled or deadline items.
|
|
|
|
Sorting can be customized using the variable
|
|
@code{org-agenda-sorting-strategy}.
|
|
|
|
@node Agenda commands, Calendar/Diary integration, Agenda, Timeline and Agenda
|
|
@section Commands in the agenda buffer
|
|
|
|
Entries in the agenda buffer are linked back to the org file or diary
|
|
file where they originate. You are not allowed to edit the agenda
|
|
buffer itself, but commands are provided to show and jump to the
|
|
original entry location, and to edit the org-files ``remotely'' from
|
|
the agenda buffer. In this way, all information is stored only once,
|
|
and you don't risk that your agenda and note files diverge.
|
|
|
|
Some commands can be executed with mouse clicks on agenda lines. For
|
|
the other commands, the cursor needs to be in the desired line. Most
|
|
commands are available for both timelines and the agenda. The
|
|
exceptions are marked.
|
|
|
|
@table @kbd
|
|
@tsubheading{Motion}
|
|
@kindex n
|
|
@item n
|
|
Next line (same as @key{up}).
|
|
@kindex p
|
|
@item p
|
|
Previous line (same as @key{down}).
|
|
@tsubheading{View/GoTo org file}
|
|
@kindex mouse-3
|
|
@kindex @key{SPC}
|
|
@item mouse-3
|
|
@itemx @key{SPC}
|
|
Display the original location of the item in another window.
|
|
|
|
@kindex l
|
|
@item l
|
|
Display original location and recenter that window.
|
|
|
|
@kindex mouse-2
|
|
@kindex @key{TAB}
|
|
@item mouse-2
|
|
@itemx @key{TAB}
|
|
Go to the original location of the item in another window.
|
|
|
|
@kindex @key{RET}
|
|
@itemx @key{RET}
|
|
Go to the original location of the item and delete other windows.
|
|
|
|
@kindex f
|
|
@item f
|
|
Toggle follow mode. In follow mode, as you move the cursor through
|
|
the agenda buffer, the other window always shows the corresponding
|
|
location in the org file.
|
|
|
|
@tsubheading{Change display}
|
|
@kindex o
|
|
@item o
|
|
Delete other windows.
|
|
|
|
@kindex w
|
|
@item w
|
|
Switch to weekly view (7 days displayed together)
|
|
|
|
@kindex d
|
|
@item d
|
|
Switch to daily view (just one day displayed)
|
|
|
|
@kindex D
|
|
@item D
|
|
Toggle the inclusion of diary entries. See @ref{Calendar/Diary integration}.
|
|
|
|
@kindex g
|
|
@item g
|
|
Toggle the time grid on and off. See also the variables
|
|
@code{org-agenda-use-time-grid} and @code{org-agenda-time-grid}.
|
|
|
|
@kindex r
|
|
@item r
|
|
Recreate the agenda buffer, for example to reflect the changes
|
|
after modification of the time stamps of items with S-@key{left} and
|
|
S-@key{right}.
|
|
|
|
@kindex @key{right}
|
|
@item @key{right}
|
|
Display the following @code{org-agenda-ndays} days. For example, if
|
|
the display covers a week, switch to the following week. With prefix
|
|
arg, go forward that many times @code{org-agenda-ndays} days. Not
|
|
available in timelines.
|
|
|
|
@kindex @key{left}
|
|
@item @key{left}
|
|
Display the previous dates. Not available in timelines.
|
|
|
|
@kindex .
|
|
@item .
|
|
Goto today.
|
|
|
|
@tsubheading{Remote editing}
|
|
|
|
@item 0-9
|
|
Digit argument.
|
|
|
|
@kindex t
|
|
@item t
|
|
Change the TODO state of the item, both in the agenda and in the
|
|
original org file.
|
|
|
|
@kindex ,
|
|
@item ,
|
|
Set the priority for the current item. Org-mode prompts for the
|
|
priority character. If you reply with @key{SPC}, the priority cookie
|
|
is removed from the entry.
|
|
|
|
@kindex P
|
|
@item p
|
|
Display weighted priority of current item.
|
|
|
|
@kindex +
|
|
@kindex S-@key{up}
|
|
@item +
|
|
@itemx S-@key{up}
|
|
Increase the priority of the current item. The priority is changed in
|
|
the original buffer, but the agenda is not resorted. Use the @kbd{r}
|
|
key for this.
|
|
|
|
@kindex -
|
|
@kindex S-@key{down}
|
|
@item -
|
|
@itemx S-@key{down}
|
|
Decrease the priority of the current item.
|
|
|
|
@kindex S-@key{right}
|
|
@item S-@key{right}
|
|
Change the time stamp associated with the current line by one day into
|
|
the future. With prefix argument, change it by that many days. For
|
|
example, @kbd{3 6 5 S-@key{right}} will change it by a year. The
|
|
stamp is changed in the original org file, but the change is not
|
|
directly reflected in the agenda buffer. Use the
|
|
@kbd{r} key to update the buffer.
|
|
|
|
@kindex S-@key{left}
|
|
@item S-@key{left}
|
|
Change the time stamp associated with the current line by one day
|
|
into the past.
|
|
|
|
@kindex >
|
|
@item >
|
|
Change the time stamp associated with the current line to today.
|
|
The key @kbd{>} has been chosen, because it is the same as @kbd{S-.}
|
|
on my keyboard.
|
|
|
|
@cindex diary entries, creating from agenda
|
|
@kindex i
|
|
@item i
|
|
Insert a new entry into the diary. Prompts for the type of entry
|
|
(day, weekly, monthly, yearly, anniversary, cyclic) and creates a new
|
|
entry in the diary, just like @kbd{i d} etc. would do in the calendar.
|
|
The date is taken from the cursor position.
|
|
|
|
@tsubheading{Calendar commands}
|
|
@kindex c
|
|
@item c
|
|
Open the Emacs calendar and move to the date at the agenda cursor.
|
|
|
|
@item c
|
|
When in the calendar, compute and show the Org-mode agenda for the
|
|
date at the cursor.
|
|
|
|
@kindex M
|
|
@item M
|
|
Show the phases of the moon for three month around current date.
|
|
|
|
@kindex S
|
|
@item S
|
|
Show sunrise and sunset times. The geographical location must be set
|
|
with calendar variables, see documentation of the Emacs calendar.
|
|
|
|
@kindex C
|
|
@item C
|
|
Convert the date at cursor into many other cultural and historic
|
|
calendars.
|
|
|
|
@kindex H
|
|
@item H
|
|
Show holidays for three month around the cursor date.
|
|
|
|
@tsubheading{Quit and Exit}
|
|
@kindex q
|
|
@item q
|
|
Quit Agenda, remove the agenda buffer.
|
|
|
|
@kindex x
|
|
@cindex agenda files, removing buffers
|
|
@item x
|
|
Exit agenda, remove the agenda buffer and all buffers loaded by Emacs
|
|
for the compilation of the agenda. Buffers created by the user to
|
|
visit org files will not be removed.
|
|
|
|
@end table
|
|
|
|
@node Calendar/Diary integration, , Agenda commands, Timeline and Agenda
|
|
@section Calendar/Diary integration
|
|
@cindex calendar integration
|
|
@cindex diary integration
|
|
|
|
Emacs contains the calendar and diary by Edward M. Reingold. The
|
|
calendar displays a three-month calendar with holidays from different
|
|
countries and cultures. The diary allows to keep track of
|
|
anniversaries, lunar phases, sunrise/set, recurrent appointments
|
|
(weekly, monthly) and more. In this way, it is quite complementary to
|
|
Org-mode. It can be very useful to combine output from Org-mode with
|
|
the diary.
|
|
|
|
The interaction between Org-mode and diary works both ways: You can
|
|
list entries from the diary in the Org-mode agenda, from which many
|
|
calendar and diary commands are directly accessible. Or you can
|
|
display entries from the org agenda in the Emacs diary.
|
|
|
|
@menu
|
|
* Diary to agenda:: Agenda incorporates the diary
|
|
* Agenda to diary:: Diary incorporates the agenda
|
|
@end menu
|
|
|
|
@node Diary to agenda, Agenda to diary, Calendar/Diary integration, Calendar/Diary integration
|
|
@subsection Including the diary into the agenda
|
|
@cindex diary to agenda
|
|
|
|
In order to include entries from the Emacs diary into Org-mode's
|
|
agenda, you only need to customize the variable
|
|
|
|
@lisp
|
|
(setq org-agenda-include-diary t)
|
|
@end lisp
|
|
@noindent
|
|
|
|
@noindent After that, everything will happen automatically. All diary
|
|
entries including holidays, anniversaries etc will be included in the
|
|
agenda buffer created by Org-mode. @key{SPC}, @key{TAB}, and
|
|
@key{RET} can be used from the agenda buffer to jump to the diary
|
|
file, in order to edit existing diary entries. The @kbd{i} command to
|
|
insert new entries for the current date works in the agenda buffer, as
|
|
well as the commands @kbd{S}, @kbd{M}, and @kbd{C} to display
|
|
Sunrise/Sunset times, show lunar phases and to convert to other
|
|
calendars, respectively. @kbd{c} can be used to switch back and forth
|
|
between calendar and agenda.
|
|
|
|
@node Agenda to diary, , Diary to agenda, Calendar/Diary integration
|
|
@subsection Including the agenda into the diary
|
|
|
|
If you prefer to use the Emacs diary as your main instrument and if
|
|
you wish to include the Org-mode agenda into it, the following steps
|
|
are necessary: Autoload the function @command{org-diary} as shown
|
|
above under @ref{Installation and Activation}. You also need to use
|
|
@emph{fancy diary display} by setting in @file{.emacs}:
|
|
|
|
@lisp
|
|
(add-hook 'diary-display-hook 'fancy-diary-display)
|
|
@end lisp
|
|
|
|
Then include the following line into your @file{~/diary} file, in
|
|
order to get the entries from all files listed in the variable
|
|
@code{org-agenda-files}:
|
|
|
|
@example
|
|
&%%(org-diary)
|
|
@end example
|
|
@noindent
|
|
You may also select specific files with
|
|
|
|
@example
|
|
&%%(org-diary) ~/path/to/some/org-file.org
|
|
&%%(org-diary) ~/path/to/another/org-file.org
|
|
@end example
|
|
|
|
If you now launch the calendar and press @kbd{d} to display a diary,
|
|
the headlines of entries containing a timestamp, date range, schedule,
|
|
or deadline referring to the selected date will be listed. Just like
|
|
in Org-mode's agenda view, the diary for @emph{today} contains
|
|
additional entries for overdue deadlines and scheduled items. See
|
|
also the documentation of the @command{org-diary} function.
|
|
|
|
@node Exporting, Miscellaneous, Timeline and Agenda, Top
|
|
@chapter Exporting
|
|
@cindex exporting
|
|
@cindex ASCII export
|
|
@cindex HTML export
|
|
|
|
@cindex headline levels, for exporting
|
|
For printing and sharing of notes, an Org-mode document can be
|
|
exported as an ASCII file, or as HTML. In the exported version, the
|
|
first 3 outline levels will become headlines, defining a general
|
|
document structure. Additional levels will be exported as itemize
|
|
lists. If you want that transition to occur at a different level,
|
|
specify it with a prefix argument. For example,
|
|
|
|
@example
|
|
@kbd{M-1 M-x org-export-as-html}
|
|
@end example
|
|
@noindent
|
|
creates only top level headlines and does the rest as items.
|
|
|
|
@menu
|
|
* Export commands:: Commands which export and display
|
|
* HTML formatting:: Interpretation of the buffer content
|
|
* Export options:: How to influence exports
|
|
* Comment lines:: Lines which will not be exported
|
|
@end menu
|
|
|
|
@node Export commands, HTML formatting, Exporting, Exporting
|
|
@section Export commands
|
|
|
|
@cindex region, active
|
|
@cindex active region
|
|
@cindex transient-mark-mode
|
|
@table @kbd
|
|
@kindex C-c C-x a
|
|
@item C-c C-x a
|
|
Export as ASCII file. If there is an active region, only the region
|
|
will be exported. For an org file @file{myfile.org}, the ASCII file
|
|
will be @file{myfile.txt}. The file will be overwritten without
|
|
warning.
|
|
@kindex C-c C-x h
|
|
@item C-c C-x h
|
|
Export as HTML file @file{myfile.html}.
|
|
@kindex C-c C-x C-h
|
|
@item C-c C-x C-h
|
|
Export as HTML file and open it with a browser.
|
|
@kindex C-c C-x t
|
|
@item C-c C-x t
|
|
Insert template with export options, see below.
|
|
@kindex C-c :
|
|
@item C-c :
|
|
Toggle fixed-width for line or region, see below.
|
|
@end table
|
|
|
|
@node HTML formatting, Export options, Export commands, Exporting
|
|
@section HTML formatting
|
|
|
|
Not all text is transferred literally to the exported HTML file. The
|
|
exporter implements the following interpretation:
|
|
|
|
@itemize @bullet
|
|
@cindex underlined text
|
|
@cindex bold text
|
|
@cindex italic text
|
|
@item
|
|
You can make words @b{*bold*}, @i{/italic/}, and _underlined_
|
|
|
|
@cindex @TeX{} interpretation
|
|
@item
|
|
Simple @TeX{}-like math constructs are interpreted:
|
|
|
|
@cindex completion, of @TeX{} symbols
|
|
@itemize @minus
|
|
@item
|
|
@samp{10^22} and @samp{J_n} are super- and subscripts. You can quote
|
|
@samp{^} and @samp{_} with a backslash: @samp{\_} and @samp{\^}
|
|
@item
|
|
@samp{\alpha} indicates a Greek letter, @samp{\to} an arrow. You can
|
|
use completion for these macros, just type @samp{\} and maybe a few
|
|
letters, and press @kbd{M-@key{TAB}} to see possible completions.
|
|
@end itemize
|
|
|
|
@cindex tables, export to HTML
|
|
@item
|
|
Tables are transformed into HTML tables. Data fields before the first
|
|
horizontal separator line will be formatted as table header fields.
|
|
|
|
@cindex fixed width
|
|
@item
|
|
Lines starting with @samp{:} are typeset in a fixed-width font, to
|
|
allow quoting of computer code etc.
|
|
|
|
@cindex HTML tags
|
|
@item
|
|
If you want to include HTML tags which should be interpreted as such,
|
|
mark them with a @samp{@@} like in @samp{@@<b>bold text@@</b>}.
|
|
Plain @samp{<} and @samp{>} are always transformed to @samp{<} and
|
|
@samp{>} in HTML export.
|
|
@end itemize
|
|
|
|
If these conversions conflict with your habits of typing ASCII text,
|
|
they can all be turned off with corresponding variables.
|
|
|
|
@node Export options, Comment lines, HTML formatting, Exporting
|
|
@section Export options
|
|
@cindex options, for export
|
|
|
|
@cindex completion, of option keywords
|
|
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-x t}. For individual lines, a good way to make sure the keyword is
|
|
correct it to type @samp{#+} and then use @kbd{M-@key{TAB}} completion
|
|
(@pxref{Completion}).
|
|
|
|
@example
|
|
#+TITLE: the title to be shown (default is the buffer name)
|
|
#+AUTHOR: the author (default taken from @code{user-full-name})
|
|
#+EMAIL: his/her email address (default from @code{user-mail-address})
|
|
#+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 *:nil TeX:t
|
|
@end example
|
|
@noindent
|
|
The OPTIONS line is a compact form to specify export settings. Here
|
|
you can
|
|
@cindex headline levels
|
|
@cindex section-numbers
|
|
@cindex table of contents
|
|
@cindex linebreak preservation
|
|
@cindex quoted html tags
|
|
@cindex fixed-width sections
|
|
@cindex tables
|
|
@cindex @TeX{}-like syntax for sub- and superscripts
|
|
@cindex emphasized text
|
|
@cindex @TeX{} macros
|
|
@example
|
|
H: @r{set the number of headline levels for export}
|
|
num: @r{turn on/off section-numbers}
|
|
toc: @r{turn on/off table of contents}
|
|
\n: @r{turn on/off linebreak-preservation}
|
|
@@: @r{turn on/off quoted html tags}
|
|
:: @r{turn on/off fixed-width sections}
|
|
|: @r{turn on/off tables}
|
|
^: @r{turn on/off @TeX{}-like syntax for sub- and superscripts.}
|
|
*: @r{turn on/off emphasized text (bold, italic, underlined)}
|
|
TeX: @r{turn on/off @TeX{} macros}
|
|
@end example
|
|
|
|
@node Comment lines, , Export options, Exporting
|
|
@section Comment lines
|
|
@cindex comment lines
|
|
@cindex exporting, not
|
|
|
|
Lines starting with @samp{#} in column zero are treated as comments
|
|
and will never be exported. Also entire subtrees starting with the
|
|
word @samp{COMMENT} will never be exported. Finally, any text before
|
|
the first headline will not be exported either.
|
|
|
|
@table @kbd
|
|
@kindex C-c ;
|
|
@item C-c ;
|
|
Toggle the COMMENT keyword at the beginning of an entry.
|
|
@end table
|
|
|
|
@node Miscellaneous, Index, Exporting, Top
|
|
@chapter Miscellaneous
|
|
|
|
@menu
|
|
* Completion:: M-TAB knows what you need
|
|
* Customization:: Adapting Org-mode to your taste
|
|
* FAQ:: Frequently asked questions
|
|
* Interaction:: Other Emacs packages
|
|
* Bugs:: Things which do not work perfectly
|
|
* Acknowledgments:: These people provided feedback and more
|
|
@end menu
|
|
|
|
@node Completion, Customization, Miscellaneous, Miscellaneous
|
|
@section Completion
|
|
@cindex completion, of @TeX{} symbols
|
|
@cindex completion, of TODO keywords
|
|
@cindex completion, of dictionary words
|
|
@cindex completion, of option keywords
|
|
@cindex completion, of keyword formulas
|
|
|
|
Org-mode supports in-buffer completion. 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.
|
|
|
|
@table @kbd
|
|
@kindex M-@key{TAB}
|
|
@item M-@key{TAB}
|
|
Complete word at point
|
|
@itemize @bullet
|
|
@item
|
|
At the beginning of a headline, complete TODO keywords.
|
|
@item
|
|
After @samp{\}, complete @TeX{} symbols supported by the exporter.
|
|
@item
|
|
After @samp{#+}, complete the special keywords like @samp{TYP_TODO} or
|
|
@samp{OPTIONS} which set file-specific options for Org-mode. When the
|
|
option keyword is already complete, pressing @kbd{M-@key{TAB}} again
|
|
will insert example settings for this keyword.
|
|
@item
|
|
After @samp{=}, complete keyword formulas for tables.
|
|
@item
|
|
Elsewhere, complete dictionary words using ispell.
|
|
@end itemize
|
|
@end table
|
|
|
|
@node Customization, FAQ, Completion, Miscellaneous
|
|
@section Customization
|
|
@cindex customization
|
|
@cindex options, for customization
|
|
@cindex variables, for customization
|
|
|
|
There is a large number of variables which can be used to customize
|
|
Org-mode. For the sake of compactness of the manual, we are not
|
|
describing the variables here. For an overview of customization
|
|
variables, use @kbd{M-x org-customize}. Or select @code{Browse Org
|
|
Group} from the @code{Org->Customization} menu.
|
|
|
|
@node FAQ, Interaction, Customization, Miscellaneous
|
|
@section Frequently asked questions
|
|
|
|
@enumerate
|
|
@item @b{Org-mode seems to be a useful default mode for the various
|
|
@file{README} files I have scattered through my directories. How do I
|
|
turn it on for all @file{README} files?}
|
|
@example
|
|
(add-to-list 'auto-mode-alist '("README$" . org-mode))
|
|
@end example
|
|
|
|
@item @b{I would like to have two windows on the same Org-mode
|
|
file, but with different outline visibility. Is that possible?}@*
|
|
@cindex @code{make-indirect-buffer}
|
|
@cindex indirect buffers
|
|
In GNU Emacs, you may use @emph{indirect buffers} which do exactly
|
|
this. See the documentation on the command
|
|
@code{make-indirect-buffer}. In XEmacs, this is currently not
|
|
possible because of the different outline implementation.
|
|
|
|
@item @b{Is there an easy way to insert links to web locations?}@*
|
|
@cindex URL, paste into buffer
|
|
Sure, just type or paste them into the buffer. A plain-text URL-like
|
|
string is directly interpreted as a link.
|
|
|
|
@item @b{When I export my TODO list, every TODO item becomes a
|
|
separate section. How do I enforce these items to be exported as an
|
|
itemized list?}@*
|
|
If you plan to use ASCII or HTML export, make sure things you want to
|
|
be exported as item lists are level 4 at least, even if that does mean
|
|
there is a level jump. For example
|
|
|
|
@example
|
|
* Todays top priorities
|
|
**** TODO write a letter to xyz
|
|
**** TODO Finish the paper
|
|
**** Pick up kids at the school
|
|
@end example
|
|
|
|
Alternatively, if you need a specific value for the heading/item
|
|
transition in a particular file, use the @samp{+OPTIONS} line to
|
|
configure the @samp{H} switch.
|
|
|
|
@example
|
|
+OPTIONS: H:2; ...
|
|
@end example
|
|
|
|
@item @b{I would like to export only a subtree of my file to HTML. How?}@*
|
|
@cindex exporting a subtree
|
|
If you want to export a subtree, mark the subtree as region and then
|
|
export. Marking can be done with @kbd{C-c @@ C-x C-x}, for example.
|
|
|
|
@item @b{Org-mode takes over the S-cursor keys. I also want to use
|
|
CUA-mode, is there a way to fix this conflict?}@*
|
|
Yes, see @ref{Interaction}
|
|
|
|
@item @b{Is there an easy way to insert an empty table template with a
|
|
default number of rows and columns?}@*
|
|
@cindex table, empty template
|
|
To insert an empty table template, just type @samp{|-} and use
|
|
@key{TAB}. The default size can be changed with the variable
|
|
@code{org-table-default-size}. However, just starting to type the
|
|
first line is usually much easier.
|
|
|
|
@item @b{One of my table columns has started to fill up with
|
|
@samp{#ERROR}. What is going on?}@*
|
|
Org-mode tried to compute the column from other fields using a
|
|
formula stored in the @samp{#+TBLFMT:} line just below the table, and
|
|
the evaluation of the formula fails. Fix the fields used in the
|
|
formula, or fix the formula, or remove it!
|
|
|
|
@item @b{When I am in the last column of a table and just above a
|
|
horizontal line in the table, pressing TAB creates a new table line
|
|
@i{before} the horizontal line. How can I quickly move to the line
|
|
@i{below} the horizontal line instead?}@*
|
|
Press @key{down} (to get on the separator line) and then @key{TAB}.
|
|
|
|
@item @b{How can I change the indentation of an entire table without
|
|
fixing every line by hand?}@*
|
|
@cindex indentation, of tables
|
|
The indentation of a table is set by the first line. So just fix the
|
|
indentation of the first line and realign with @key{TAB}.
|
|
|
|
@end enumerate
|
|
|
|
|
|
@node Interaction, Bugs, FAQ, Miscellaneous
|
|
@section Interaction with other packages
|
|
@cindex packages, interaction with other
|
|
Org-mode can cooperate with the following packages:
|
|
|
|
@table @asis
|
|
@cindex @file{table.el}
|
|
@item @file{table.el} by Takaaki Ota
|
|
Org mode cooperates with table.el, see @ref{table.el}.
|
|
@cindex @file{calc.el}
|
|
@item @file{calc.el} by Dave Gillespie
|
|
Org-mode uses the calc package for implementing spreadsheet
|
|
functionality in its tables (@pxref{Table calculations}). Org-modes
|
|
checks for the availability of calc by looking for the function
|
|
@code{calc-eval} which should be autoloaded in your setup if calc has
|
|
been installed properly. As of Emacs 22, calc is part of the Emacs
|
|
distribution. Another possibility for interaction between the two
|
|
packages is using calc for embedded calculations. @xref{Embedded Mode,
|
|
, Embedded Mode, calc, The calc maanual}.
|
|
@cindex @file{constants.el}
|
|
@item @file{constants.el} by Carsten Dominik
|
|
In a table formula (@pxref{Table calculations}), it is possible to use
|
|
names for natural constants or units. Instead of defining you own
|
|
constants in the variable @code{org-table-formula-constants}, install
|
|
the @file{constants} package which defines a large number of constants
|
|
and units, and lets you use unit prefixes like @samp{M} for
|
|
@samp{Mega} etc. You will need version 2.0 of this package, available
|
|
at @url{http://www.astro.uva.nl/~dominik/Tools}. Org-mode checks for
|
|
the function @code{constants-get}, which has to be autoloaded in your
|
|
setup. See the installation instructions in the file
|
|
@file{constants.el}.
|
|
@cindex @file{remember.el}
|
|
@cindex @file{CUA.el}
|
|
@item @file{CUA.el} by Kim. F. Storm
|
|
Keybindings in Org-mode conflict with the @kbd{S-<cursor>} keys
|
|
used by CUA-mode (as well as pc-select-mode and s-region-mode) to
|
|
select and extend the region. If you want to use one of these
|
|
packages along with Org-mode, configure the variable
|
|
@code{org-CUA-compatible}. When set, Org-mode will move the following
|
|
keybindings in org-mode files, and in the agenda buffer (but not
|
|
during date selection).
|
|
@example
|
|
S-UP -> M-p S-DOWN -> M-n
|
|
S-LEFT -> M-- S-RIGHT -> M-+
|
|
S-RET -> C-S-RET
|
|
@end example
|
|
Yes, these are unfortunately more difficult to remember. If you want
|
|
to have other replacement keys, look at the variable
|
|
@code{org-disputed-keys}.
|
|
@item @file{remember.el} by John Wiegley
|
|
Org mode cooperates with remember, see @ref{Remember}.
|
|
@cindex @file{planner.el}
|
|
@item @file{planner.el} by John Wiegley
|
|
Planner is another tool to plan work and keep track of tasks. Planner
|
|
uses a multi-file approach with project pages and day pages. Is based
|
|
on Emacs-Wiki. If Planner is your primary tool, it can be useful to
|
|
display the agenda entries resulting from org files in day-pages of
|
|
the planner. This can be done through the diary of the calendar:
|
|
Integrate org files into the diary as described above, and then turn
|
|
on the diary support of planner.
|
|
@end table
|
|
|
|
@node Bugs, Acknowledgments, Interaction, Miscellaneous
|
|
@section Bugs
|
|
@cindex bugs
|
|
|
|
Here is a list of things which should work differently, but which I
|
|
have found too hard to fix.
|
|
|
|
@itemize @bullet
|
|
@item
|
|
If you call @code{fill-paragraph} (bound to @kbd{M-q}) in a table, the
|
|
filling is correctly disabled. However, if some text directly
|
|
(without an empty line in between) preceeds or follows a table, calling
|
|
@code{fill-paragraph} in that text will also fill the table like
|
|
normal text. Also, @code{fill-region} does bypass the
|
|
@code{fill-paragraph} code and will fill tables like normal text.
|
|
@item
|
|
When the application called by @kbd{C-c C-o} to open a file link fails
|
|
(for example because the application does not exits or refuses to open
|
|
the file), it does so silently. No error message is displayed.
|
|
@item
|
|
Recalculating a table line applies the formulas from left to right.
|
|
If a formula calculated fields further down the row, multiple
|
|
recalculation may be needed to get all fields consistent.
|
|
@item
|
|
Under XEmacs, if Org-mode entries are included into the diary, it is
|
|
not possible to jump back from the diary to the org file. Apparently,
|
|
the text properties are lost when the fancy-diary-display is used.
|
|
However, from Org-mode's timeline and agenda buffers (created with
|
|
@kbd{C-c C-r} and @kbd{C-c a}), things do work correctly.
|
|
@item
|
|
Linux should also have a default viewer application, using mailcap.
|
|
Maybe we can use GNUS or VM mime code? Or dired's guessing commands?
|
|
Any hints (or even patches) are appreciated.
|
|
@item
|
|
When you write @samp{x = a /b/ c}, b will be exported in italics.
|
|
@item
|
|
The exporters work well, but could be made more efficient.
|
|
@end itemize
|
|
|
|
@page
|
|
|
|
@node Acknowledgments, , Bugs, Miscellaneous
|
|
@section Acknowledgments
|
|
@cindex acknowledgments
|
|
|
|
Org-mode was written by Carsten Dominik, who still maintains it at the
|
|
Org-mode homepage @uref{http://www.astro.uva.nl/~dominik/Tools/org/}.
|
|
The following people have helped the development along with ideas,
|
|
suggestions and patches.
|
|
|
|
@itemize @bullet
|
|
@item
|
|
Matthias Rempe (Oelde) provided ideas, a patch introducing Windows
|
|
NT/2000 support, and quality control.
|
|
@item
|
|
Kevin Rogers contributed code to access VM files on remote hosts.
|
|
@item
|
|
Juergen Vollmer contributed code generating the table of contents
|
|
in HTML output, and other export improvements.
|
|
@item
|
|
Christian Egli converted the documentation into TeXInfo format. He
|
|
also showed me his plans for a multifile summary for Org-mode. Some of
|
|
his ideas have found their way into the agenda.
|
|
@item
|
|
Philip Rooke created the Org-mode reference card. He also helped with
|
|
beta testing and contributed a number of very useful ideas.
|
|
@item
|
|
Christian Schlauer proposed angular brackets around links, among other
|
|
things.
|
|
@item
|
|
David Wainberg suggested to implement an archiving mechanism.
|
|
@item
|
|
Linking to VM/BBDB/GNUS was inspired by Tom Shannon's
|
|
@file{organizer-mode.el}.
|
|
@item
|
|
Scheduling TODO items was inspired by John Wiegley's @file{planner.el}.
|
|
@item
|
|
Sacha Chua, the current maintainer of Planner, offered linking code
|
|
from Planner. I made use of the offer for links to RMAIL and Wanderlust.
|
|
@item
|
|
Oliver Oppitz sent several useful suggestions.
|
|
@item
|
|
Carsten Wimmer suggested some changes and helped fix a bug in linking
|
|
to GNUS.
|
|
@item
|
|
Pavel Chalmoviansky reported bugs and suggested improvements related
|
|
to the agenda treatment of items with specified time.
|
|
@item
|
|
Stefan Monnier provided a patch with lots of little fixes to keep the
|
|
Emacs-Lisp compiler happy.
|
|
@item
|
|
Kai Grossjohann pointed out that a number of key bindings in Org-mode
|
|
conflict with other packages.
|
|
@end itemize
|
|
|
|
@node Index, Key Index, Miscellaneous, Top
|
|
@chapter Index
|
|
|
|
@printindex cp
|
|
|
|
@node Key Index, , Index, Top
|
|
@chapter Key Index
|
|
|
|
@printindex ky
|
|
|
|
@bye
|