[Emacs-diffs] Changes to emacs/man/org.texi

[Carsten Dominik]

Index: emacs/man/org.texi
diff -u emacs/man/org.texi:1.37 emacs/man/org.texi:1.38
--- emacs/man/org.texi:1.37     Wed Dec 28 20:07:06 2005
+++ emacs/man/org.texi  Thu Jan  5 08:06:36 2006
@@ -4,12 +4,13 @@
 @setfilename ../info/org
 @settitle Org Mode Manual
 
address@hidden VERSION 4.01
address@hidden DATE December 2005
address@hidden VERSION 4.02
address@hidden DATE January 2006
 
 @dircategory Emacs
 @direntry
-* Org Mode: (org).     outline-based notes management and organizer.
+* Org Mode: (org).     outline-based notes management and organizer
+
 @end direntry
 
 @c Version and Contact Info
@@ -35,7 +36,7 @@
 @copying
 This manual is for Org-mode (version @value{VERSION}).
 
-Copyright @copyright{} 2004, 2005 Free Software Foundation
+Copyright @copyright{} 2004, 2005, 2006 Free Software Foundation
 
 @quotation
 Permission is granted to copy, distribute and/or modify this document
@@ -105,7 +106,7 @@
 * Structure editing::           Changing sequence and level of headlines
 * Archiving::                   Move done task trees to a different place
 * Sparse trees::                Matches embedded in context
-* Tags::                        
+* Tags::                        Tagging headlines and matching sets of tags
 * Plain Lists::                 Editing hand-formatted lists
 
 Tables
@@ -152,17 +153,20 @@
 
 Agenda Views
 
-* Agenda::                      Your weekly planner
-* Global TODO list::            Overview over all things to do
-* Matching headline tags::      Select information based on tags
+* Agenda files::                Files being searched for agenda information
+* Agenda dispatcher::           Keyboard access to agenda views
+* Weekly/Daily Agenda::         The calendar page with current tasks
+* Global TODO list::            All infinished action items
+* Matching headline tags::      Structured information with fine-tuned search
 * Timeline::                    Time-sorted view for single file
 * Agenda commands::             Remote editing of org trees
-* Calendar/Diary integration::  Integrating Anniversaries and more
 
-Calendar/Diary integration
+Weekly/Daily Agenda
 
-* Diary to agenda::             Agenda incorporates the diary
-* Agenda to diary::             Diary incorporates the agenda
+* Categories::                  Not all tasks are equal
+* Time-of-day specifications::  How the agenda knows the time
+* Calendar/Diary integration::  Integrating Anniversaries and more
+* Sorting of agenda items::     The order of things
 
 Exporting
 
@@ -333,7 +337,7 @@
 * Structure editing::           Changing sequence and level of headlines
 * Archiving::                   Move done task trees to a different place
 * Sparse trees::                Matches embedded in context
-* Tags::                        
+* Tags::                        Tagging headlines and matching sets of tags
 * Plain Lists::                 Editing hand-formatted lists
 @end menu
 
@@ -563,7 +567,8 @@
 @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 address@hidden also the variable
+headline structure above address@hidden also the variables
address@hidden and
 @code{org-show-following-heading}.}.  Just try it out and you will see
 immediately how it works.
 
@@ -581,8 +586,20 @@
 the match.  Each match is also highlighted, the highlights disappear
 when the buffer is changed with an editing command.
 @end table
address@hidden
+For frequently used sparse trees of specific search strings, you can
+use the variable @code{org-agenda-custom-commands} to define fast
+keyboard access to specific sparse trees.  These commands will then be
+accessible through the agenda dispatcher (@pxref{Agenda dispatcher}).
+For example
address@hidden
+(setq org-agenda-custom-commands
+      '(("f" occur-tree "FIXME")))
address@hidden lisp
address@hidden will define the key @kbd{C-c a f} as a shortcut for creating
+a sparse tree matching the string @samp{FIXME}.
 
-Other commands are using this feature as well.  For example @kbd{C-c
+Other commands are using sparse trees as well.  For example @kbd{C-c
 C-v} creates a sparse TODO tree (@pxref{TODO basics}).
 
 @kindex C-c C-x v
@@ -655,6 +672,11 @@
 @item C-c a m
 Create a global list of tag matches from all agenda files.
 @xref{Matching headline tags}.
address@hidden C-c a M
address@hidden C-c a M
+Create a global list of tag matches from all agenda files, but check
+only TODO items and force checking subitems (see variable
address@hidden).
 @end table
 
 A tags search string can use Boolean operators @samp{&} for AND and
@@ -1650,7 +1672,7 @@
 @kindex C-c a t
 @item C-c a t
 Show the global TODO list.  This collects the TODO items from all
-agenda files (@pxref{Agenda}) into a single buffer.  The buffer is in
+agenda files (@pxref{Agenda Views}) into a single buffer.  The buffer is in
 @code{agenda-mode}, so there are commands to examine and manipulate
 the TODO entries directly from that buffer (@pxref{Agenda commands}).
 @xref{Global TODO list}, for more information.
@@ -1674,9 +1696,9 @@
 @samp{CLOSED: [timestamp]} will be inserted just after the headline.
 If you turn the entry back into a TODO item again through further
 state cycling, that line will be removed again.  In the timeline
-(@pxref{Timeline}) and in the agenda (@pxref{Agenda}), you can then
-use the @kbd{L} key to display the TODO items closed on each day,
-giving you an overview of what has been done on a day.
+(@pxref{Timeline}) and in the agenda (@pxref{Weekly/Daily Agenda}),
+you can then use the @kbd{L} key to display the TODO items closed on
+each day, giving you an overview of what has been done on a day.
 
 @node TODO extensions, Priorities, Progress Logging, TODO items
 @section Extended use of TODO keywords
@@ -1814,7 +1836,7 @@
 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}).
+difference only in the agenda (@pxref{Weekly/Daily Agenda}).
 
 @table @kbd
 @kindex @kbd{C-c ,}
@@ -1859,7 +1881,7 @@
 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:
+dates in the agenda (@pxref{Weekly/Daily Agenda}).  We distinguish:
 
 @table @var
 @cindex timestamp
@@ -1944,7 +1966,7 @@
 @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}).
+(@pxref{Weekly/Daily Agenda}).
 
 @kindex C-c C-d
 @item C-c C-d
@@ -2035,37 +2057,14 @@
 @chapter Agenda Views
 @cindex agenda views
 
-Org-mode can select items based of various criteria, and display them
-in a separate buffer.  The information to be shown is collected from
-all @emph{agenda files}, the files listed in the variable
address@hidden  Thus even if you only work with a single
-Org-mode file, this file must be put into that address@hidden
-using the dispatcher pressing @kbd{1} before selecting a command will
-actually limit the command to the current file, and ignore
address@hidden until the next dispatcher command.}.  You can
-customize @code{org-agenda-files}, but the easiest way to maintain it
-is through the following commands
-
address@hidden files, adding to agenda list
address@hidden @kbd
address@hidden C-c [
address@hidden C-c [
-Add current file to the list of agenda files.  The file is added to
-the front of the list.  If it was already in the list, it is moved to
-the front.  With prefix arg, file is added/moved to the end.
address@hidden C-c ]
address@hidden C-c ]
-Remove current file from the list of agenda files.
address@hidden C-,
address@hidden C-,
-Cycle through agenda file list.
address@hidden table
address@hidden
-The Org menu always contains the current list of files and can be used
-to quickly visit any of them.
+Due to the way Org-mode works, TODO items and time-stamped items can
+be scattered throughout a file or even a number of files.  To get an
+overview over open action items, or over events that are important for
+a particular date, this information must be collected, sorted and
+displayed in an organized way.
 
-Org-mode provides three different views on the information in these
-files: 
+Org-mode can select items based on various criteria, and display them
+in a separate buffer.  Three different views are provided:
 @itemize @bullet
 @item
 an @emph{agenda} that is like a calendar and shows information
@@ -2074,7 +2073,7 @@
 a @emph{TODO list} that covers all unfinished
 action items, and
 @item
-a @emph{tags view} that show information based on
+a @emph{tags view} that shows information based on
 the tags associated with headlines in the outline tree.
 @end itemize
 @noindent
@@ -2083,37 +2082,103 @@
 corresponding locations in the original Org-mode files, and even to
 edit these files remotely.
 
address@hidden
+* Agenda files::                Files being searched for agenda information
+* Agenda dispatcher::           Keyboard access to agenda views
+* Weekly/Daily Agenda::         The calendar page with current tasks
+* Global TODO list::            All unfinished action items
+* Matching headline tags::      Structured information with fine-tuned search
+* Timeline::                    Time-sorted view for single file
+* Agenda commands::             Remote editing of org trees
address@hidden menu
+
address@hidden Agenda files, Agenda dispatcher, Agenda Views, Agenda Views
address@hidden Agenda files
+
+The information to be shown is collected from all @emph{agenda files},
+the files listed in the variable @code{org-agenda-files}.  Thus even
+if you only work with a single Org-mode file, this file should be put
+into that address@hidden using the dispatcher pressing @kbd{1}
+before selecting a command will actually limit the command to the
+current file, and ignore @code{org-agenda-files} until the next
+dispatcher command.}.  You can customize @code{org-agenda-files}, but
+the easiest way to maintain it is through the following commands
+
address@hidden files, adding to agenda list
address@hidden @kbd
address@hidden C-c [
address@hidden C-c [
+Add current file to the list of agenda files.  The file is added to
+the front of the list.  If it was already in the list, it is moved to
+the front.  With prefix arg, file is added/moved to the end.
address@hidden C-c ]
address@hidden C-c ]
+Remove current file from the list of agenda files.
address@hidden C-,
address@hidden C-,
+Cycle through agenda file list.
address@hidden table
address@hidden
+The Org menu contains the current list of files and can be used
+to visit any of them.
+
address@hidden Agenda dispatcher, Weekly/Daily Agenda, Agenda files, Agenda 
Views
address@hidden The agenda dispatcher
address@hidden agenda dispatcher
address@hidden dispatching agenda commands
 @cindex custom agenda commands
 @cindex agenda commands, custom
 The views are created through a dispatcher that should be bound to a
 global key, for example @kbd{C-c a} (@pxref{Installation and
 Activation}).  In the following we will assume that @kbd{C-c a} is
 indeed how the dispatcher is accessed and list keyboard access to
-commands accordingly.  The dispatcher offers a number of default
-commands, for example to create a TODO list or a the calendar-like
-agenda.  You can also define a number of custom searches for tags and
-specific TODO keywords through the variable
address@hidden
address@hidden C-c a C
-These commands will be offered by the dispatcher just like the default
-commands.  If you press @kbd{C-c a C}, you will get a customization
-buffer for this variable.
+commands accordingly.  After pressing @kbd{C-c a}, an additional
+letter is required to execute a command.  The dispatcher offers the
+following default commands:
address@hidden @kbd
address@hidden a
+Create the calendar-like agenda (@pxref{Weekly/Daily Agenda}).
address@hidden t / T
+Create a list of all TODO items (@pxref{Global TODO list}).
address@hidden m / M
+Create a list of headline matching a TAGS expression (@pxref{Matching
+headline tags}).
address@hidden table
+
+You can also define custom commands that will be accessible through
+the dispatcher, just like the default commands.  Custom commands are
+global searches for tags and specific TODO keywords, or a variety of
+sparse tree creating commands (@pxref{Sparse trees}).  As sparse trees
+are only defined for a single org-mode file, these latter commands act
+on the current buffer instead of the list of agenda files.
 
address@hidden
-* Agenda::                      Your weekly planner
-* Global TODO list::            Overview over all things to do
-* Matching headline tags::      Select information based on tags
-* Timeline::                    Time-sorted view for single file
-* Agenda commands::             Remote editing of org trees
-* Calendar/Diary integration::  Integrating Anniversaries and more
address@hidden menu
address@hidden C-c a C
+Custom commands are configured in the variable
address@hidden  You can customize this variable,
+for example by pressing @kbd{C-c a C}.  You can also directly set it
+with Emacs Lisp in @file{.emacs}.  For example:
address@hidden
+(setq org-agenda-custom-commands
+      '(("w" todo "WAITING")
+        ("u" tags "+BOSS-URGENT")
+        ("U" tags-tree "+BOSS-URGENT")
+        ("f" occur-tree "\\<FIXME\\>")))
address@hidden lisp
address@hidden will define @kbd{C-c a w} as a global search for
+TODO entries with @samp{WAITING} as todo keyword, @kbd{C-c a u} as a
+global tags search for headlines marked @samp{:BOSS:} but not
address@hidden:URGENT:}, @kbd{C-c a U} to do the same search but only in the
+current buffer and display the result as a sparse tree, and @kbd{C-c a
+f} to create a sparse tree with all entries containing the word
address@hidden  For more information, look at the documentation string
+of the variable @code{org-agenda-custom-commands}.
 
address@hidden Agenda, Global TODO list, Agenda Views, Agenda Views
address@hidden Agenda
address@hidden Weekly/Daily Agenda, Global TODO list, Agenda dispatcher, Agenda 
Views
address@hidden The weekly/daily agenda
 @cindex agenda
 
-The purpose of the @emph{agenda} is to act like a week/day page of a
-paper agenda, showing you all the tasks for the current week or day.
+The purpose of the weekly/daily @emph{agenda} is to act like a page of
+a paper agenda, showing all the tasks for the current week or day.
 
 @table @kbd
 @cindex org-agenda, command
@@ -2124,8 +2189,6 @@
 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 address@hidden
-The key binding @kbd{C-c a a} is only a suggestion - see
address@hidden and Activation}.
 @end table
 
 Remote editing from the agenda buffer means for example that you can
@@ -2133,7 +2196,14 @@
 The commands available in the Agenda buffer are listed in @ref{Agenda
 commands}.
 
address@hidden
+* Categories::                  Not all tasks are equal
+* Time-of-day specifications::  How the agenda knows the time
+* Calendar/Diary integration::  Integrating Anniversaries and more
+* Sorting of agenda items::     The order of things
address@hidden menu
 
address@hidden Categories, Time-of-day specifications, Weekly/Daily Agenda, 
Weekly/Daily Agenda
 @subsection Categories
 
 @cindex category
@@ -2147,6 +2217,7 @@
 for the text below it.  The display in the agenda buffer looks best if
 the category is not longer than 10 characters.
 
address@hidden Time-of-day specifications, Calendar/Diary integration, 
Categories, Weekly/Daily Agenda
 @subsection Time-of-Day Specifications
 
 Org-mode checks each agenda item for a time-of-day specification.  The
@@ -2194,6 +2265,39 @@
 @code{org-agenda-time-grid}.
 
 
address@hidden Calendar/Diary integration, Sorting of agenda items, Time-of-day 
specifications, Weekly/Daily Agenda
address@hidden Calendar/Diary integration
address@hidden calendar integration
address@hidden 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.
+
+In order to include entries from the Emacs diary into Org-mode's
+agenda, you only need to customize the variable
+
address@hidden
+(setq org-agenda-include-diary t)
address@hidden lisp
address@hidden
+
address@hidden 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
address@hidden 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.
+
address@hidden Sorting of agenda items,  , Calendar/Diary integration, 
Weekly/Daily Agenda
 @subsection Sorting of agenda items
 @cindex sorting, of agenda items
 @cindex priorities, of agenda items
@@ -2211,7 +2315,8 @@
 Sorting can be customized using the variable
 @code{org-agenda-sorting-strategy}.
 
address@hidden Global TODO list, Matching headline tags, Agenda, Agenda Views
+
address@hidden Global TODO list, Matching headline tags, Weekly/Daily Agenda, 
Agenda Views
 @section The global TODO list
 @cindex global TODO list
 @cindex TODO list, global
@@ -2223,20 +2328,21 @@
 @kindex C-c a t
 @item C-c a t
 Show the global TODO list.  This collects the TODO items from all
-agenda files (@pxref{Agenda}) into a single buffer.  The buffer is in
+agenda files (@pxref{Agenda Views}) into a single buffer.  The buffer is in
 @code{agenda-mode}, so there are commands to examine and manipulate
 the TODO entries directly from that buffer (@pxref{Agenda commands}).
 @xref{Global TODO list}, for more information.
 @kindex C-c a T
 @item C-c a T
 Like the above, but allow to select a specific TODO keyword.  You can
-also do this by specifying a prefix argument.  With a @kbd{C-u} prefix
-you are prompted for a keyword.  With a numeric prefix, the Nth
-keyword in @code{org-todo-keywords} is selected.
+also do this by specifying a prefix argument to @kbd{C-c a t}.  With a
address@hidden prefix you are prompted for a keyword.  With a numeric
+prefix, the Nth keyword in @code{org-todo-keywords} is selected.
 @kindex r
 The @kbd{r} key in the agenda buffer regenerates it, and you can give
 a prefix argument to this command to change the selected TODO keyword,
-for example @kbd{3 r}.
+for example @kbd{3 r}.  If you often need a search for a specific
+keyword, define a custom command for it (@pxref{Agenda dispatcher}).
 @end table
 
 Remote editing of TODO items means that you can change the state of a
@@ -2258,11 +2364,13 @@
 Produce a list of all headlines that match a given set of tags.  The
 command prompts for a selection criterion, which is a boolean logic
 expression with tags, like @samp{+WORK+URGENT-WITHBOSS} or
address@hidden|HOME} (@pxref{Tags}).
address@hidden|HOME} (@pxref{Tags}).  If you often need a specific search,
+define a custom command for it (@pxref{Agenda dispatcher}).
 @kindex C-c a M
 @item C-c a M
-Like @kbd{C-c a m}, but only select headlines that are also TODO
-items.
+Like @kbd{C-c a m}, but only select headlines that are also TODO items
+and force checking subitems (see variable
address@hidden
 @end table
 
 The commands available in the tags list are described in @ref{Agenda
@@ -2294,7 +2402,7 @@
 The commands available in the timeline buffer are listed in
 @ref{Agenda commands}.
 
address@hidden Agenda commands, Calendar/Diary integration, Timeline, Agenda 
Views
address@hidden Agenda commands,  , Timeline, Agenda Views
 @section Commands in the agenda buffer
 @cindex commands, in agenda buffer
 
@@ -2306,9 +2414,7 @@
 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.
+the other commands, the cursor needs to be in the desired line.
 
 @table @kbd
 @tsubheading{Motion}
@@ -2384,12 +2490,11 @@
 @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.
+arg, go forward that many times @code{org-agenda-ndays} days.
 
 @kindex @key{left}
 @item @key{left}
-Display the previous dates.  Not available in timelines.
+Display the previous dates.
 
 @kindex .
 @item .
@@ -2491,7 +2596,6 @@
 @kindex C-c C-x C-c
 @item C-c C-x C-c
 Export a single iCalendar file containing entries from all agenda files.
-Not available in timelines.
 
 @tsubheading{Quit and Exit}
 @kindex q
@@ -2507,88 +2611,6 @@
 
 @end table
 
address@hidden Calendar/Diary integration,  , Agenda commands, Agenda Views
address@hidden Calendar/Diary integration
address@hidden calendar integration
address@hidden 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.
-
address@hidden
-* Diary to agenda::             Agenda incorporates the diary
-* Agenda to diary::             Diary incorporates the agenda
address@hidden menu
-
address@hidden Diary to agenda, Agenda to diary, Calendar/Diary integration, 
Calendar/Diary integration
address@hidden Including the diary into the agenda
address@hidden diary to agenda
-
-In order to include entries from the Emacs diary into Org-mode's
-agenda, you only need to customize the variable
-
address@hidden
-(setq org-agenda-include-diary t)
address@hidden lisp
address@hidden
-
address@hidden 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
address@hidden 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.
-
address@hidden Agenda to diary,  , Diary to agenda, Calendar/Diary integration
address@hidden Including the agenda into the diary
address@hidden agenda to 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
address@hidden diary display} by setting in @file{.emacs}:
-
address@hidden
-(add-hook 'diary-display-hook 'fancy-diary-display)
address@hidden lisp
-
-Then include the following line into your @file{~/diary} file, in
-order to get the entries from all files listed in the variable
address@hidden:
-
address@hidden
-&%%(org-diary)
address@hidden example
address@hidden
-You may also select specific files with
-
address@hidden
-&%%(org-diary) ~/path/to/some/org-file.org
-&%%(org-diary) ~/path/to/another/org-file.org
address@hidden 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, Agenda Views, Top
 @chapter Exporting
 @cindex exporting
@@ -3021,6 +3043,42 @@
 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}.
 
address@hidden @b{Is it possible to include entries from org-mode files into my
+emacs address@hidden 
+Since the org-mode agenda is much more powerful and can contain the
+diary (@pxref{Calendar/Diary integration}), you should think twice
+before deciding to do this.  Inegrating org-mode information into the
+diary is, however, possible.  The following steps are necessary:
+Autoload the function @command{org-diary} as shown above under
address@hidden and Activation}.  You also need to use @emph{fancy
+diary display} by setting in @file{.emacs}:
+
address@hidden
+(add-hook 'diary-display-hook 'fancy-diary-display)
address@hidden lisp
+
+Then include the following line into your @file{~/diary} file, in
+order to get the entries from all files listed in the variable
address@hidden:
+
address@hidden
+&%%(org-diary)
address@hidden example
address@hidden
+You may also select specific files with
+
address@hidden
+&%%(org-diary) ~/path/to/some/org-file.org
+&%%(org-diary) ~/path/to/another/org-file.org
address@hidden 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.
+
 @end enumerate