Mercurial > emacs

changeset 63362:8a4e1b582425

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Version 3.11
author Carsten Dominik <dominik@science.uva.nl>
date Mon, 13 Jun 2005 06:43:12 +0000
parents 6e51bee08dae
children 8420228eae66
files man/org.texi
diffstat 1 files changed, 152 insertions(+), 79 deletions(-) [+]
line wrap: on
line diff
--- a/man/org.texi	Mon Jun 13 06:42:53 2005 +0000
+++ b/man/org.texi	Mon Jun 13 06:43:12 2005 +0000
@@ -4,8 +4,8 @@
 @setfilename ../info/org
 @settitle Org Mode Manual
 
-@set VERSION 3.10
-@set DATE May 2005
+@set VERSION 3.11
+@set DATE June 2005
 
 @dircategory Emacs
 @direntry
@@ -103,6 +103,7 @@
 * 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
@@ -158,8 +159,8 @@
 * 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
-* Bugs::                        Things which do not work perfectly
 
 @end detailmenu
 @end menu
@@ -303,6 +304,7 @@
 * 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
 
@@ -426,7 +428,7 @@
 visible.
 @end table
 
-@node Structure editing, Sparse trees, Motion, Document Structure
+@node Structure editing, Archiving, Motion, Document Structure
 @section Structure editing
 @cindex structure editing
 @cindex headline, promotion and demotion
@@ -487,7 +489,30 @@
 inside a table (@pxref{Tables}), the Meta-Cursor keys have different
 functionality.
 
-@node Sparse trees,  , Structure editing, Document Structure
+@node Archiving, Sparse trees, Structure editing, Document Structure
+@section Archiving
+@cindex archiving
+
+When an 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 @kbd{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
@@ -702,7 +727,8 @@
 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.
+incremented during copy.  This key is also used by CUA-mode
+(@pxref{Interaction}).
 
 @cindex formula, in tables
 @cindex calculations, in tables
@@ -807,33 +833,35 @@
 @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.
-The following list shows examples for each link type.
+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                           @r{A shell command}
+<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 the end of
-the line or, in tables, by the end of the table field.  Therefore,
-outside of tables there can be only one link per line (but see the
-variable @code{org-allow-space-in-links}).
+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
@@ -854,10 +882,11 @@
 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.  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.
+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
@@ -930,9 +959,11 @@
            Or use prefix arg to specify level manually.
 @end multitable
 
-So the fastest way to store the note is to press @kbd{C-c C-c @key{RET}
-@key{RET}} to append it to the default file.  But with little extra
-effort, you can push it directly to the correct location.
+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{*}.
@@ -1140,6 +1171,8 @@
 @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 is also used by CUA-mode
+(@pxref{Interaction}).
 @end table
 
 
@@ -1267,7 +1300,8 @@
 @kindex S-@key{right}
 @item S-@key{left}
 @itemx S-@key{right}
-Change date at cursor by one day.
+Change date at cursor by one day.  These key bindings conflict with
+CUA-mode (@pxref{Interaction}).
 
 @kindex S-@key{up}
 @kindex S-@key{down}
@@ -1275,8 +1309,10 @@
 @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}).
+a time stamp, these same keys modify the priority of an item.
+(@pxref{Priorities}). These key bindings conflict with CUA-mode
+(@pxref{Interaction}).
+
 
 @kindex C-c C-y
 @cindex evaluate time range
@@ -1872,7 +1908,8 @@
 
 @cindex tables, export to HTML
 @item
-Tables are transformed into HTML tables.
+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
@@ -1960,8 +1997,8 @@
 * 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
-* Bugs::                        Things which do not work perfectly
 @end menu
 
 @node Completion, Customization, Miscellaneous, Miscellaneous
@@ -2024,9 +2061,7 @@
 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., which visit
-the same file, but have separate settings, also for outline
-visibility.
+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
@@ -2060,12 +2095,17 @@
 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}. 
+@code{org-table-default-size}.  However, just starting to type the
+first line is usually much easier.
 
 @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
@@ -2082,7 +2122,7 @@
 @end enumerate
 
 
-@node Interaction, Acknowledgments, FAQ, Miscellaneous
+@node Interaction, Bugs, FAQ, Miscellaneous
 @section Interaction with other packages
 @cindex packages, interaction with other
 @cindex @file{planner.el}
@@ -2106,11 +2146,64 @@
 @cindex @file{table.el}
 @item @file{table.el} by Takaaki Ota
 Org mode cooperates with table.el, see @ref{table.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 folowing
+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}. 
+
 @end table
 
-@page  @c FIXME
+@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.
 
-@node Acknowledgments, Bugs, Interaction, Miscellaneous
+@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 follws 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 
+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
 
@@ -2136,13 +2229,18 @@
 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, and some
+other useful stuff.
+@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 suggested to take some
-linking code from Planner, which I did (for RMAIL and Wanderlust).
+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
@@ -2150,38 +2248,13 @@
 to GNUS.
 @item
 Pavel Chalmoviansky reported bugs and suggested improvements related
-to the agenda treatment of items with specifed time.
+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.
-@end itemize
-
-@node Bugs,  , Acknowledgments, 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 
-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 
-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.
+@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