diff man/org.texi @ 83531:a387c138b28e

Merged from [e-mail] Patches applied: * [e-mail]/emacs--devo--0--patch-305 Update from CVS * [e-mail]/emacs--devo--0--patch-306 Update from CVS * [e-mail]/emacs--devo--0--patch-307 Update from CVS: lispref/display.texi (Forcing Redisplay): Fix typo. * [e-mail]/emacs--devo--0--patch-308 Update from CVS * [e-mail]/emacs--devo--0--patch-309 Update from CVS * [e-mail]/emacs--devo--0--patch-310 Update from CVS * [e-mail]/emacs--devo--0--patch-311 Update from CVS * [e-mail]/emacs--devo--0--patch-312 Update from CVS * [e-mail]/emacs--devo--0--patch-313 Merge from gnus--rel--5.10 * [e-mail]/emacs--devo--0--patch-314 Update from CVS * [e-mail]/emacs--devo--0--patch-315 Update from CVS * [e-mail]/emacs--devo--0--patch-316 Update from CVS * [e-mail]/emacs--devo--0--patch-317 Merge from gnus--rel--5.10 * [e-mail]/emacs--devo--0--patch-318 Update from CVS * [e-mail]/emacs--devo--0--patch-319 Update from CVS * [e-mail]/emacs--devo--0--patch-320 Update from CVS * [e-mail]/emacs--devo--0--patch-321 Merge from gnus--rel--5.10 * [e-mail]/emacs--devo--0--patch-322 Update from CVS * [e-mail]/emacs--devo--0--patch-323 lisp/play/cookie1.el (cookie): Work properly when there's only one entry * [e-mail]/emacs--devo--0--patch-324 Update from CVS * [e-mail]/emacs--devo--0--patch-325 Update from CVS * [e-mail]/emacs--devo--0--patch-326 Update from CVS * [e-mail]/emacs--devo--0--patch-327 Update from CVS * [e-mail]/emacs--devo--0--patch-328 Update from CVS * [e-mail]/emacs--devo--0--patch-329 Update from CVS * [e-mail]/emacs--devo--0--patch-330 Update from CVS * [e-mail]/gnus--rel--5.10--patch-105 Update from CVS * [e-mail]/gnus--rel--5.10--patch-106 Update from CVS * [e-mail]/gnus--rel--5.10--patch-107 Update from CVS * [e-mail]/gnus--rel--5.10--patch-108 Merge from emacs--devo--0 * [e-mail]/gnus--rel--5.10--patch-109 Clean up merge mistakes * [e-mail]/gnus--rel--5.10--patch-110 Update from CVS git-archimport-id: [e-mail]--2004/emacs--multi-tty--0--patch-571

--- a/man/org.texi	Mon Jun 12 07:27:12 2006 +0000
+++ b/man/org.texi	Tue Jun 27 15:06:36 2006 +0000
@@ -3,7 +3,7 @@
 @setfilename ../info/org
 @settitle Org Mode Manual
 
-@set VERSION 4.37
+@set VERSION 4.39
 @set DATE June 2006
 
 @dircategory Emacs
@@ -83,9 +83,12 @@
 * Timestamps::                  Assign date and time to items
 * Tags::                        Tagging headlines and matching sets of tags
 * Agenda views::                Collecting information into views
+* Embedded LaTeX::              LaTeX fragments and formulas
 * Exporting::                   Sharing and publishing of notes
 * Publishing::                  Create a web site of linked Org-mode files
 * Miscellaneous::               All the rest which did not fit elsewhere
+* Extensions and Hacking::      It is possible to write add-on code
+* History and Acknowledgments::  How Org-mode came into being 
 * Index::                       The fast road to specific information
 * Key Index::                   Key bindings and where they are described
 
@@ -95,7 +98,7 @@
 Introduction
 
 * Summary::                     Brief summary of what Org-mode does
-* Installation and activation::  How to install Org-mode
+* Installation::                How to install Org-mode
 * Feedback::                    Bug reports, ideas, patches etc.
 
 Document Structure
@@ -109,6 +112,11 @@
 * Sparse trees::                Matches embedded in context
 * Plain lists::                 Editing hand-formatted lists
 
+Archiving
+
+* ARCHIVE tag::                 Marking a tree as inactive
+* Moving subtrees::             Moving a tree to an archive file
+
 Tables
 
 * Built-in table editor::       Simple tables
@@ -162,7 +170,7 @@
 
 Progress Logging
 
-* Closing items::               When was this entry makred DONE?
+* Closing items::               When was this entry marked DONE?
 * Clocking work time::          When exactly did you work on this item?
 
 Tags
@@ -188,6 +196,14 @@
 * Calendar/Diary integration::  Integrating Anniversaries and more
 * Sorting of agenda items::     The order of things
 
+Embedded LaTeX
+
+* Math symbols::                TeX macros for symbols and greek letters
+* Subscripts and Superscripts::  Simple syntax for raising/lowering text
+* LaTeX fragments::             Complex formulas made easy
+* Processing LaTeX fragments::  Previewing LaTeX processing
+* CDLaTeX mode::                Speed up entering of formulas
+
 Exporting
 
 * ASCII export::                Exporting to plain ASCII
@@ -211,7 +227,7 @@
 Configuration
 
 * Project alist::               The central configuration variable
-* File sources and destinations::  From here to there
+* Sources and destinations::    From here to there
 * Selecting files::             What files are part of the project?
 * Publishing action::           Setting the function doing the publishing
 * Publishing options::          Tweaking HTML export
@@ -227,21 +243,23 @@
 
 * Completion::                  M-TAB knows what you need
 * Customization::               Adapting Org-mode to your taste
-* Summary of in-buffer settings::  Using special lines to set options
+* In-buffer settings::          Overview of the #+KEYWORDS
 * The very busy C-c C-c key::   When in doubt, press C-c C-c
 * Clean view::                  Getting rid of leading stars in the outline
 * TTY keys::                    Using Org-mode on a tty
-* FAQ::                         Frequently asked questions
 * Interaction::                 Other Emacs packages
 * Bugs::                        Things which do not work perfectly
-* Acknowledgments::             These people provided feedback and more
 
 Interaction with other packages
 
-* Extensions::                  Third-party extensions for Org-mode
 * Cooperation::                 Packages Org-mode cooperates with
 * Conflicts::                   Packages that lead to conflicts
 
+Extensions, Hooks and Hacking
+
+* Extensions::                  Existing 3rd-part extensions
+* Dynamic blocks::              Automatically filled blocks
+
 @end detailmenu
 @end menu
 
@@ -251,11 +269,11 @@
 
 @menu
 * Summary::                     Brief summary of what Org-mode does
-* Installation and activation::  How to install Org-mode
+* Installation::                How to install Org-mode
 * Feedback::                    Bug reports, ideas, patches etc.
 @end menu
 
-@node Summary, Installation and activation, Introduction, Introduction
+@node Summary, Installation, Introduction, Introduction
 @section Summary
 @cindex summary
 
@@ -296,14 +314,15 @@
 The Org-mode table editor can be integrated into any major mode by
 activating the minor Orgtbl-mode.
 
+@cindex FAQ
 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
+version of Org-mode, as well as additional information, frequently asked
+questions (FAQ), links to tutorials etc.  This page is located at
 @uref{http://www.astro.uva.nl/~dominik/Tools/org/}.
 
 @page
 
-@node Installation and activation, Feedback, Summary, Introduction
+@node Installation, Feedback, Summary, Introduction
 @section Installation and Activation
 @cindex installation
 @cindex autoload
@@ -341,6 +360,10 @@
 (require 'org-install)
 @end lisp
 
+If you use Org-mode with XEmacs, you also need to install the file
+@file{noutline.el} from the @file{xemacs} subdirectory of the Org-mode
+distribution.
+
 @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
@@ -354,7 +377,7 @@
 the file's name is.  See also the variable
 @code{org-insert-mode-line-in-empty-file}.
 
-@node Feedback,  , Installation and activation, Introduction
+@node Feedback,  , Installation, Introduction
 @section Feedback
 @cindex feedback
 @cindex bug reports
@@ -614,26 +637,89 @@
 @node Archiving, Sparse trees, Structure editing, Document structure
 @section Archiving
 @cindex archiving
-@cindex filing subtrees
 
 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.
+to move the tree out of the way and to stop it from contributing to the
+agenda.  Org-mode knows two ways of archiving.  You can mark a tree with
+the ARCHIVE tag, or you can move an entire (sub)tree to a different
+location.
+
+@menu
+* ARCHIVE tag::                 Marking a tree as inactive
+* Moving subtrees::             Moving a tree to an archive file
+@end menu
+
+@node ARCHIVE tag, Moving subtrees, Archiving, Archiving
+@subsection The ARCHIVE tag
+@cindex internal archiving
+
+A headline that is marked with the ARCHIVE tag (@pxref{Tags}) stays at
+its location in the outline tree, but behaves in the following way:
+@itemize @minus
+@item
+It does not open when you attempt to do so with a visibility cycling
+command (@pxref{Visibility cycling}).  You can still open it with a
+normal outline command like @code{show-all}.  Or you can modify the
+option @code{org-cycle-open-archived-trees}.
+@item
+During sparse tree construction (@pxref{Sparse trees}), matches in
+archived subtrees are not exposed, unless you configure the option
+@code{org-sparse-tree-open-archived-trees}.
+@item
+During agenda view construction (@pxref{Agenda views}), the content of
+archived trees is ignored unless you configure the option
+@code{org-agenda-skip-archived-trees}.
+@item
+Archived trees are not exported (@pxref{Exporting}), only the headline
+is.  Configure the details using the variable
+@code{org-export-with-archived-trees}.
+@end itemize
+
+The following commands allow to set or clear the ARCHIVE tag:
+
+@table @kbd
+@kindex C-c C-x C-a
+@item C-c C-x C-a
+Toggle the ARCHIVE tag for the current headline.  When the tag is set,
+the headline changes to a shadowish face, and the subtree below it is
+hidden.
+@kindex C-u C-c C-x C-a
+@item C-u C-c C-x C-a
+Check if any direct children of the current headline should be archived.
+To do this, each subtree is checked for open TODO entries.  If none are
+found, the command offers to set the ARCHIVE tag for the child.  If the
+cursor is @emph{not} on a headline when this command is invoked, the
+level 1 trees will be checked.
+@end table
+
+@node Moving subtrees,  , ARCHIVE tag, Archiving
+@subsection Moving subtrees
+@cindex external archiving
+
+Once an entire project is finished, you may want to move it to a
+different location, either in the current file, or even in a different
+file, the archive file.
+
 @table @kbd
 @kindex C-c $
-@item @kbd{C-c $}
+@item C-c $
 Archive the subtree starting at the cursor position to the location
 given by @code{org-archive-location}.
+@kindex C-u C-c $
+@item C-u C-c $
+Check if any direct children of the current headline could be moved to
+the archive.  To do this, each subtree is checked for open TODO entries.
+If none are found, the command offers to move it to the archive
+location.  If the cursor is @emph{not} on a headline when this command
+is invoked, the level 1 trees will be checked.
 @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.
+The default archive location is a file in the same directory as the
+current file, with the name derived by appending @file{_archive} to the
+current file name.  For information and examples on how to change this,
+see the documentation string of the variable
+@code{org-archive-location}.
 
 @node Sparse trees, Plain lists, Archiving, Document structure
 @section Sparse trees
@@ -806,6 +892,7 @@
 list at the cursor.
 @end table
 
+
 @node Tables, Hyperlinks, Document structure, Top
 @chapter Tables
 @cindex tables
@@ -1663,8 +1750,7 @@
 automatically created link is not working correctly or accurately
 enough, you can write custom functions to select the search string and
 to do the search for particular file types - see @ref{Custom searches}.
-The key binding @kbd{C-c l} is only a suggestion - see @ref{Installation
-and activation}.
+The key binding @kbd{C-c l} is only a suggestion - see @ref{Installation}.
 
 @kindex C-c C-l
 @cindex link completion
@@ -1674,7 +1760,11 @@
 Insert a link.  This prompts for a link to be inserted into the buffer.
 You can just type a link, using text for an internal link, or one of the
 link type prefixes mentioned in the examples above.  Through completion,
-all links stored during the current session can be accessed.  The link
+all links stored during the current session can be
+accessed@footnote{After insertion of a stored link, the link will be
+removed from the list of stored links.  To keep it in the list later
+use, use a triple @kbd{C-u} prefix to @kbd{C-c C-l}, or configure the
+option @code{org-keep-stored-link-after-insertion}.}.  The link
 will be inserted into the buffer, along with a descriptive text.  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
@@ -1711,11 +1801,11 @@
 corresponding search.  When the cursor is on a TAG list in a headline,
 it creates the corresponding TAGS view.  If the cursor is on a time
 stamp, it compiles the agenda for that date.  Furthermore, it will visit
-text files in @samp{file:} links 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 you want to
-override the default application and visit the file with Emacs, use a
-@kbd{C-u} prefix.
+text and remote files in @samp{file:} links with Emacs and select a
+suitable application for local non-text files.  Classification of files
+is based on file extension only.  See option @code{org-file-apps}.  If
+you want to override the default application and visit the file with
+Emacs, use a @kbd{C-u} prefix.
 
 @kindex mouse-2
 @kindex mouse-1
@@ -2227,10 +2317,9 @@
 @item Time range with CLOCK keyword
 @cindex CLOCK keyword
 When using the clock to time the work that is being done on specific
-items, time ranges preceeded by the CLOCK keyword are inserted
+items, time ranges preceded by the CLOCK keyword are inserted
 automatically into the file.  The time stamps are enclosed in square
 brackets instead of angular brackets.  @xref{Clocking work time}.
-@c FIXME: Reference needed
 @end table
 
 @node Creating timestamps, Progress logging, Time stamps, Timestamps
@@ -2376,7 +2465,7 @@
 stop working on an aspect of a project.
 
 @menu
-* Closing items::               When was this entry makred DONE?
+* Closing items::               When was this entry marked DONE?
 * Clocking work time::          When exactly did you work on this item?
 @end menu
 
@@ -2405,8 +2494,8 @@
 
 Org-mode allows you to clock the time you spent on specific tasks in a
 project.  When you start working on an item, you can start the clock.
-When you stop working on that tast, or when you makr the task done, the
-clock is stoppend and the corresponding time interval is recorded.  It
+When you stop working on that task, or when you mark the task done, the
+clock is stopped and the corresponding time interval is recorded.  It
 also computes the total time spent on each subtree of a project.
 
 @table @kbd
@@ -2435,6 +2524,22 @@
 recorded under that heading, including the time of any subheadings. You
 can use visibility cycling to study the tree, but the overlays disappear
 automatically when the buffer is changed.
+@kindex C-c C-x C-r
+@item C-c C-x C-r
+Insert a dynamic block containing a clock report as an org-mode table
+into the current file.
+@example
+#+BEGIN: clocktable :maxlevel 2 :emphasize nil
+
+#+END: clocktable
+@end example
+@noindent
+If such a block already exists, its content is replaced by the new
+table.  The @samp{BEGIN} line can specify options:
+@example
+:maxlevels   @r{Maximum level depth to which times are listed in the table.}
+:emphasize   @r{When @code{t}, emphasize level one and level two items}
+@end example
 @end table
 
 The @kbd{l} key may be used in the timeline (@pxref{Timeline}) and in
@@ -2612,7 +2717,7 @@
 @samp{WORK|LAPTOP&NIGHT} requires that the @samp{:LAPTOP:} lines are
 also tagged @samp{NIGHT}.
 
-@node Agenda views, Exporting, Tags, Top
+@node Agenda views, Embedded LaTeX, Tags, Top
 @chapter Agenda Views
 @cindex agenda views
 
@@ -2693,12 +2798,11 @@
 @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.  After pressing @kbd{C-c a}, an additional
-letter is required to execute a command.  The dispatcher offers the
-following default commands:
+global key, for example @kbd{C-c a} (@pxref{Installation}).  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.  After
+pressing @kbd{C-c a}, an additional letter is required to execute a
+command.  The dispatcher offers the following default commands:
 @table @kbd
 @item a
 Create the calendar-like agenda (@pxref{Weekly/Daily agenda}).
@@ -3092,6 +3196,10 @@
 @item :
 Set tags for the current headline.
 
+@kindex a
+@item a
+Toggle the ARCHIVE tag for the current headline.
+
 @kindex ,
 @item ,
 Set the priority for the current item.  Org-mode prompts for the
@@ -3208,7 +3316,200 @@
 
 @end table
 
-@node Exporting, Publishing, Agenda views, Top
+@node Embedded LaTeX, Exporting, Agenda views, Top
+@chapter Embedded LaTeX
+@cindex @TeX{} interpretation
+@cindex La@TeX{} interpretation
+
+Plain ASCII is normally sufficient for almost all note taking.  One
+exception, however, are scientific notes which need to be able to
+contain mathematical symbols and the occasional formula.
+La@TeX{}@footnote{La@TeX{} is a macro system based on Donald E. Knuth's
+@TeX{} system.  Many of the features described here as ``La@TeX{}'' are
+really from @TeX{}, but for simplicity I am blurring this distinction.}
+is widely used to typeset scientific documents. Org-mode supports
+embedding La@TeX{} code into its files, because many academics are used
+to read La@TeX{} source code, and because it can be readily processed
+into images for HTML production.
+
+It is not necessary to mark La@TeX{} macros and code in any special way.
+If you observe a few conventions, Org-mode knows how to find it and what
+to do with it.
+
+@menu
+* Math symbols::                TeX macros for symbols and Greek letters
+* Subscripts and Superscripts::  Simple syntax for raising/lowering text
+* LaTeX fragments::             Complex formulas made easy
+* Processing LaTeX fragments::  Previewing LaTeX processing
+* CDLaTeX mode::                Speed up entering of formulas
+@end menu
+
+@node Math symbols, Subscripts and Superscripts, Embedded LaTeX, Embedded LaTeX
+@section Math symbols
+
+You can use La@TeX{} macros to insert special symbols like @samp{\alpha}
+to indicate the Greek letter, or @samp{\to} to indicate an arrow.
+Completion for these macros is available, just type @samp{\} and maybe a
+few letters, and press @kbd{M-@key{TAB}} to see possible completions.
+Unlike La@TeX{} code, Org-mode allows these macros to be present
+without surrounding math delimiters, for example:
+
+@example
+Angles are written as Greek letters \alpha, \beta and \gamma.
+@end example
+
+During HTML export (@pxref{HTML export}), these symbols are translated
+into the proper syntax for HTML, for the above examples this is
+@samp{α} and @samp{→}, respectively.
+
+@node Subscripts and Superscripts, LaTeX fragments, Math symbols, Embedded LaTeX
+@section Subscripts and Superscripts
+
+Just like in La@TeX{}, @samp{^} and @samp{_} are used to indicate super-
+and subscripts.  Again, these can be used without embedding them in
+math-mode delimiters.  To increase the readability of ASCII text, it is
+not necessary (but OK) to surround multi-character sub- and superscripts
+with curly braces.  For example
+
+@example
+The mass if the sun is M_sun = 1.989 x 10^30 kg.  The radius o
+the sun is R_@{sun@} = 6.96 x 10^8 m.
+@end example
+
+To avoid interpretation as raised or lowered text, you can quote
+@samp{^} and @samp{_} with a backslash: @samp{\_} and @samp{\^}.
+
+During HTML export (@pxref{HTML export}), subscript and superscripts
+are surrounded with @code{<sub>} and @code{<sup>} tags, respectively.
+
+@node LaTeX fragments, Processing LaTeX fragments, Subscripts and Superscripts, Embedded LaTeX
+@section LaTeX fragments
+
+With symbols, sub- and superscripts, HTML is pretty much at its end when
+it comes to representing mathematical formulas.  More complex
+expressions need a dedicated formula processor.  To this end, Org-mode
+can contain arbitrary La@TeX{} fragments.  It provides commands to
+preview the typeset result of these fragments, and upon export to HTML,
+all fragments will be converted to images and inlined into the HTML
+document.  For this to work you need to be on a system with a working
+La@TeX{} installation.  You also need the @file{dvipng} program,
+available at @url{http://sourceforge.net/projects/dvipng/}.
+
+La@TeX{} fragments don't need any special marking at all.  The following
+snippets will be identified as LaTeX source code:
+@itemize @bullet
+@item
+Environments of any kind.  The only requirement is that the
+@code{\begin} statements appears on a new line, preceded by only
+whitespace.
+@item
+Text within the usual La@TeX{} math delimiters.  Org-mode recognizes
+single @samp{$} characters as math delimiters only if they are directly
+attached to the surrounded text, with no whitespace in between.  For the
+other delimiters, there is no such restriction.
+@end itemize
+
+@noindent For example:
+
+@example
+\begin@{equation@}                          % arbitrary environments,
+x=\sqrt@{b@}                                % even tables, figures
+\end@{equation@}                            % etc
+
+If $a=\sqrt@{b@}$ and \( b=2 \), then the solution must be
+either $$ a=+\sqrt@{2@} $$ or \[ a=-\sqrt@{2@} \].
+@end example
+
+@noindent
+If you need any of the delimiter ASCII sequences for other purposes, you
+can configure the option @code{org-format-latex-options} to deselect the
+ones you do not wish to have interpreted by the La@TeX{} converter.
+
+@node Processing LaTeX fragments, CDLaTeX mode, LaTeX fragments, Embedded LaTeX
+@section Processing LaTeX fragments
+
+La@TeX{} fragments can be processed to produce a preview images of the
+typeset expressions:
+
+@table @kbd
+@kindex C-c C-x C-l
+@item C-c C-x C-l
+Produce a preview image of the La@TeX{} fragment at point and overlay it
+over the source code.  If there is no fragment at point, process all
+fragments in the current entry (between two headlines).  When called
+with a prefix argument, process the entire subtree.  When called with
+two prefix arguments, or when the cursor is before the first headline,
+process the entire buffer.
+@kindex C-c C-c
+@item C-c C-c
+Remove the overlay preview images.
+@end table
+
+During HTML export (@pxref{HTML export}), all La@TeX{} fragments are
+converted into images and inlined into the document if the following
+setting is active:
+
+@lisp
+(setq org-export-with-LaTeX-fragments t)
+@end lisp
+
+@node CDLaTeX mode,  , Processing LaTeX fragments, Embedded LaTeX
+@section Using CDLaTeX to enter math
+
+CDLaTeX-mode is a minor mode that is normally used in combination with a
+major LaTeX mode like AUCTeX in order to speed-up insertion of
+environments and math templates.  Inside Org-mode, you can make use of
+some of the features of cdlatex-mode by turning on a special minor mode
+with @code{M-x org-cdlatex-mode}.  You can also turn it on for all
+Org-mode files with
+
+@lisp
+(add-hook 'org-mode-hook 'turn-on-org-cdlatex)
+@end lisp
+
+When this mode is enabled, the following features are present (for more
+details see the documentation of cdlatex-mode):
+@itemize @bullet
+@kindex C-c @{
+@item
+Environment templates can be inserted with @kbd{C-c @{}.
+@item
+@kindex @key{TAB}
+The @key{TAB} key will do template expansion if the cursor is inside a
+LaTeX fragment@footnote{Org-mode has a heuristic method to test if the
+cursor is inside such a fragment, see the documentation of the function
+@code{org-inside-LaTeX-fragment-p}.}.  For example, @key{TAB} will
+expand @code{fr} to @code{\frac@{@}@{@}} and position the cursor
+correctly inside the first brace.  Another @key{TAB} will get you into
+the second brace.  Even outside fragments, @key{TAB} will expand
+environment abbreviations at the beginning of a line.  For example, if
+you write @samp{equ} at the beginning of a line and press @key{TAB},
+this abbreviation will be expanded to an @code{equation} environment.
+To get a list of all abbreviations, type @kbd{M-x
+cdlatex-command-help}. 
+@item
+@kindex _
+@kindex ^
+Pressing @kbd{_} and @kbd{^} inside a LaTeX fragment will insert these
+characters together with a pair of braces.  If you use @key{TAB} to move
+out of the braces, and if the braces surround only a single character or
+macro, they are removed again (depending on the variable
+@code{cdlatex-simplify-sub-super-scripts}).
+@item
+@kindex `
+Pressing the backquote @kbd{`} followed by a character inserts math
+macros, also outside LaTeX fragments.  If you wait more than 1.5 seconds
+after the backquote, a help window will pop up.
+@item
+@kindex '
+Pressing the normal quote @kbd{'} followed by another character modifies
+the symbol before point with an accent or a font.  If you wait more than
+1.5 seconds after the backquote, a help window will pop up.  Character
+modification will work only inside La@TeX{} fragments, outside the quote
+is normal.
+@end itemize
+
+@node Exporting, Publishing, Embedded LaTeX, Top
 @chapter Exporting
 @cindex exporting
 
@@ -3470,7 +3771,6 @@
 has a number of typing conventions that allow to produce a richly
 formatted output.
 
-
 @itemize @bullet
 
 @cindex hand-formatted lists
@@ -3484,22 +3784,14 @@
 @cindex bold text
 @cindex italic text
 @item
-You can make words @b{*bold*}, @i{/italic/}, and _underlined_
-
-@cindex @TeX{} interpretation
+You can make words @b{*bold*}, @i{/italic/}, _underlined_,
+@code{=code=}, and @samp{+strikethrough+}.
+
+@cindex LaTeX fragments, export
+@cindex TeX macros, export
 @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
+Many @TeX{} macros and entire La@TeX{} fragments are converted into HTML
+entities or images (@pxref{Embedded LaTeX}).
 
 @cindex tables, export
 @item
@@ -3531,6 +3823,7 @@
 which explains how to set export options with special lines in a
 buffer.
 
+
 @node Export options,  , Enhancing text, Text interpretation
 @subsection Export options
 @cindex options, for export
@@ -3556,7 +3849,7 @@
 #+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
+#+OPTIONS:   H:2 num:t toc:t \n:nil @@:t ::t |:t ^:t *:nil TeX:t LaTeX:t
 @end example
 
 @noindent
@@ -3572,6 +3865,7 @@
 @cindex @TeX{}-like syntax for sub- and superscripts
 @cindex emphasized text
 @cindex @TeX{} macros
+@cindex La@TeX{} fragments
 @example
 H:      @r{set the number of headline levels for export}
 num:    @r{turn on/off section-numbers}
@@ -3582,11 +3876,13 @@
 |:      @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}
+TeX:    @r{turn on/off simple @TeX{} macros in plain text}
+LaTeX:  @r{turn on/off La@TeX{} fragments}
 @end example
 
 @node Publishing, Miscellaneous, Exporting, Top
 @chapter Publishing
+@cindex publishing
 
 Org-mode includes@footnote{@file{org-publish.el} is not yet part of
 emacs, so if you are using @file{org.el} as it comes with Emacs, you
@@ -3615,7 +3911,7 @@
 
 @menu
 * Project alist::               The central configuration variable
-* File sources and destinations::  From here to there
+* Sources and destinations::    From here to there
 * Selecting files::             What files are part of the project?
 * Publishing action::           Setting the function doing the publishing
 * Publishing options::          Tweaking HTML export
@@ -3623,8 +3919,10 @@
 * Project page index::          Publishing a list of project files
 @end menu
 
-@node Project alist, File sources and destinations, Configuration, Configuration
+@node Project alist, Sources and destinations, Configuration, Configuration
 @subsection The variable @code{org-publish-project-alist}
+@cindex org-publish-project-alist
+@cindex projects, for publishing
 
 Org-publish is configured almost entirely through setting the value of
 one variable, called @code{org-publish-project-alist}.
@@ -3649,8 +3947,9 @@
 options. When you publish such a ``meta-project'' all the components
 will also publish.
 
-@node File sources and destinations, Selecting files, Project alist, Configuration
+@node Sources and destinations, Selecting files, Project alist, Configuration
 @subsection Sources and destinations for files
+@cindex directories, for publishing
 
 Most properties are optional, but some should always be set. In
 particular, org-publish needs to know where to look for source files,
@@ -3664,8 +3963,9 @@
 @end multitable
 @noindent
 
-@node Selecting files, Publishing action, File sources and destinations, Configuration
+@node Selecting files, Publishing action, Sources and destinations, Configuration
 @subsection Selecting files
+@cindex files, selecting for publishing
 
 By default, all files with extension @file{.org} in the base directory
 are considered part of the project.  This can be modified by setting the
@@ -3687,6 +3987,7 @@
 
 @node Publishing action, Publishing options, Selecting files, Configuration
 @subsection Publishing Action
+@cindex action, for publishing
 
 Publishing means that a file is copied to the destination directory and
 possibly transformed in the process.  The default transformation is to
@@ -3711,6 +4012,7 @@
 
 @node Publishing options, Publishing links, Publishing action, Configuration
 @subsection Options for the HTML exporter
+@cindex options, for publishing
 
 The property list can be used to set many export options for the HTML
 exporter.  In most cases, these properties correspond to user variables
@@ -3723,9 +4025,11 @@
 @item @code{:headline-levels}       @tab @code{org-export-headline-levels}
 @item @code{:section-numbers}       @tab @code{org-export-with-section-numbers}
 @item @code{:table-of-contents}     @tab @code{org-export-with-toc}
+@item @code{:archived-trees}        @tab @code{org-export-with-archived-trees}
 @item @code{:emphasize}             @tab @code{org-export-with-emphasize}
 @item @code{:sub-superscript}       @tab @code{org-export-with-sub-superscripts}
 @item @code{:TeX-macros}            @tab @code{org-export-with-TeX-macros}
+@item @code{:LaTeX-fragments}       @tab @code{org-export-with-LaTeX-fragments}
 @item @code{:fixed-width}           @tab @code{org-export-with-fixed-width}
 @item @code{:timestamps}           .@tab @code{org-export-with-timestamps}
 @item @code{:tags}                 .@tab @code{org-export-with-tags}
@@ -3752,6 +4056,7 @@
 
 @node Publishing links, Project page index, Publishing options, Configuration
 @subsection Links between published files
+@cindex links, publishing
 
 To create a link from one Org-mode file to another, you would use
 something like @samp{[[file:foo.org][The foo]]} or simply
@@ -3765,8 +4070,27 @@
 org-publish to upload the related files, these links will work
 too. @ref{Complex example} for an example of this usage.
 
+Sometime an Org-mode file to be published may contain links that are
+only valid in your production environment, but not in the publishing
+location.  In this case, use the property 
+
+@multitable @columnfractions 0.4 0.6
+@item @code{:link-validation-function}
+@tab Function to validate links
+@end multitable
+
+@noindent
+to define a function for checking link validity.  This function must
+accept two arguments, the file name and a directory relative to which
+the file name is interpreted in the production environment.  If this
+function returns @code{nil}, then the HTML generator will only insert a
+description into the HTML file, but no link.  One option for this
+function is @code{org-publish-validate-link} which checks if the given
+file is part of any project in @code{org-publish-project-alist}.
+
 @node Project page index,  , Publishing links, Configuration
 @subsection Project page index
+@cindex index, of published pages
 
 The following properties may be used to control publishing of an
 index of files or summary page for a given project.
@@ -3891,20 +4215,18 @@
 functions normally only publish changed files. You can override this and
 force publishing of all files by giving a prefix argument. 
 
-@node Miscellaneous, Index, Publishing, Top
+@node Miscellaneous, Extensions and Hacking, Publishing, Top
 @chapter Miscellaneous
 
 @menu
 * Completion::                  M-TAB knows what you need
 * Customization::               Adapting Org-mode to your taste
-* Summary of in-buffer settings::  Using special lines to set options
+* In-buffer settings::          Overview of the #+KEYWORDS
 * The very busy C-c C-c key::   When in doubt, press C-c C-c
 * Clean view::                  Getting rid of leading stars in the outline
 * TTY keys::                    Using Org-mode on a tty
-* 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
@@ -3950,8 +4272,7 @@
 @end itemize
 @end table
 
-
-@node Customization, Summary of in-buffer settings, Completion, Miscellaneous
+@node Customization, In-buffer settings, Completion, Miscellaneous
 @section Customization
 @cindex customization
 @cindex options, for customization
@@ -3963,9 +4284,9 @@
 variables is available with @kbd{M-x org-customize}.  Or select
 @code{Browse Org Group} from the @code{Org->Customization} menu.  Many
 settings can also be activated on a per-file basis, by putting special
-lines into the buffer (@pxref{Summary of in-buffer settings}).
-
-@node Summary of in-buffer settings, The very busy C-c C-c key, Customization, Miscellaneous
+lines into the buffer (@pxref{In-buffer settings}).
+
+@node In-buffer settings, The very busy C-c C-c key, Customization, Miscellaneous
 @section Summary of in-buffer settings
 @cindex in-buffer settings
 @cindex special keywords
@@ -4035,7 +4356,7 @@
 @ref{Export options}.
 @end table
 
-@node The very busy C-c C-c key, Clean view, Summary of in-buffer settings, Miscellaneous
+@node The very busy C-c C-c key, Clean view, In-buffer settings, Miscellaneous
 @section The very busy C-c C-c key
 @kindex C-c C-c
 
@@ -4043,14 +4364,13 @@
 mentioned scattered throughout this manual.  One specific function of
 this key is to add @emph{tags} to a headline (@pxref{Tags}).  In many
 other circumstances it means something like @emph{Hey Org-mode, look
-here and update according to what you see here}.  Here is a summary of what
-this means in different contexts.
+here and update according to what you see here}.  Here is a summary of
+what this means in different contexts.
 
 @itemize @minus
-@c @item
-@c If the cursor is in a headline, prompt for tags and insert them
-@c into the current line, aligned to `org-tags-column'.  When called
-@c with prefix arg, realign all tags in the current buffer.
+@item
+If there are highlichts in the buffer from the creation of a sparse
+tree, or from clock display, remove these highlights.
 @item
 If the cursor is in one of the special @code{#+KEYWORD} lines, this
 triggers scanning the buffer for these lines and updating the
@@ -4180,7 +4500,7 @@
 RET} in that file.  The reverse operation is @kbd{M-x
 org-convert-to-oddeven-levels}.
 
-@node TTY keys, FAQ, Clean view, Miscellaneous
+@node TTY keys, Interaction, Clean view, Miscellaneous
 @section Using org-mode on a tty
 @cindex tty keybindings
 
@@ -4217,251 +4537,19 @@
 @item @kbd{S-@key{down}}    @tab @kbd{C-c C-x @key{down}}  @tab
 @end multitable
 
-@node FAQ, Interaction, TTY keys, Miscellaneous
-@section Frequently asked questions
-@cindex FAQ
-
-@enumerate
-@cindex @code{keymapp nil} error
-@item @b{When I try to use Org-mode, I always get
-@code{(wrong-type-argument keymapp nil)}}.@*
-@cindex allout.el, conflict with
-This is a conflict with an outdated version of the @file{allout.el}.
-See @ref{Conflicts}.
-
-@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?}
-
-@lisp
-(add-to-list 'auto-mode-alist '("README$" . org-mode))
-@end lisp
-
-@item @b{I would like to use editing features of org-mode in other
-modes, is this possible?}@*
-@c
-Not really.  For tables there is @code{orgtbl-mode} which implements the
-table editor as a minor mode.  For other features you need to switch to
-Org-mode temporarily, or prepare text in a different buffer.
-
-@item @b{Can I get the visibility-cycling features in outline-mode and
-outline-minor-mode?}@* 
-@c
-Yes, these functions are written in a way that they are independent of
-the outline setup.  The following setup provides standard Org-mode
-functionality in outline-mode on @key{TAB} and @kbd{S-@key{TAB}}.  For
-outline-minor-mode, we use @kbd{C-@key{TAB}} instead of @key{TAB},
-because @key{TAB} usually has mode-specific tasks.
-@lisp
-(add-hook 'outline-minor-mode-hook
-  (lambda ()
-    (define-key outline-minor-mode-map [(control tab)] 'org-cycle)
-    (define-key outline-minor-mode-map [(shift tab)] 'org-global-cycle)))
-(add-hook 'outline-mode-hook
-  (lambda ()
-    (define-key outline-mode-map [(tab)] 'org-cycle)
-    (define-key outline-mode-map [(shift tab)] 'org-global-cycle)))
-@end lisp
-
-Or check out @file{outline-magic.el}, which does this and also provides
-promotion and demotion functionality.  @file{outline-magic.el} is
-available at @url{http://www.astro.uva.nl/~dominik/Tools/OutlineMagic}.
-
-@item @b{Some of my links stopped working after I upgraded to a version
-4.20 or later.  Why is this, and how can I fix it?}@*
-@c
-These must be links in plain text, containing white space, such as
-@samp{bbdb:Richard Stallman}.  You need to protect these links by
-putting double brackets around them, like @samp{[[bbdb:Richard
-Stallman]]}.
-
-@item @b{I see that Org-mode now creates links using the double bracket
-convention that hides the link part and the brackets, only showing the
-description part.  How can I convert my old links to this new format?}@*
-@c
-Execute once in each Org-mode file: @kbd{M-x org-upgrade-old-links}.
-This replaces angular brackets with the new link format.
-
-@item @b{I don't care if you find the new bracket links great, I am
-attached to the old style using angular brackets and no hiding of the
-link text.  Please give them back to me, don't tell me it is not
-possible!}@*
-@c
-Would I let you down like that?  If you must, you can do this
-
-@lisp
-(setq org-link-style 'plain
-      org-link-format "<%s>")
-@end lisp
-
-@item @b{When I am executing shell/elisp links I always get a 
-confirmation prompt and need to type @kbd{yes @key{RET}}, that's 4 key
-presses!  Can I get rid of this?}@*
-@c
-@cindex shell links, confirmation
-@cindex dangerous commands
-The confirmation is there to protect you from unwantingly execute
-potentially dangerous commands.  For example, imagine a link
-@samp{[[shell:rm -rf ~/*][Google Search]]}.  In an Org-mode buffer, this
-command would look like @samp{Google Search}, but really it would remove
-your home directory.  If you wish, you can make it easier to respond to
-the query by setting @code{org-confirm-shell-link-function} and/or
-@code{org-confirm-elisp-link-function} to @code{y-or-n-p}.  Then a
-single @kbd{y} keypress will be enough to confirm those links.  It is
-also possible to turn off this check entirely, but I do not recommend to
-do this.  Be warned.
-
-@item @b{All these stars are driving me mad, I just find the Emacs
-outlines unreadable. Can't you just put white space and a single star as a
-starter for headlines?}@*
-@c
-See @ref{Clean view}.
-
-@item @b{I would like to have two windows on the same Org-mode
-file, but with different outline visibility.  Is that possible?}@*
-@c
-@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{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?}@*
-@c
-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?}@*
-@c
-@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{Conflicts}.
-
-@item @b{One of my table columns has started to fill up with
-@samp{#ERROR}.  What is going on?}@*
-@c
-Org-mode tried to compute the column from other fields using a
-formula stored in the @samp{#+TBLFM:} 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?}@*
-@c
-Press @key{down} (to get on the separator line) and then @key{TAB}.
-Or configure the variable @code{org-table-tab-jumps-over-hlines}.
-
-@item @b{How can I change the indentation of an entire table without
-fixing every line by hand?}@*
-@c
-@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}.
-
-@item @b{Is it possible to include entries from org-mode files into my
-emacs diary?}@*
-@c
-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.  Integrating Org-mode information into the
-diary is, however, possible.  You need to turn on @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
-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.  Under XEmacs, it is
-not possible to jump back from the diary to the org, this works only in
-the agenda buffer.
-
-@end enumerate
-
-
-@node Interaction, Bugs, FAQ, Miscellaneous
+@node Interaction, Bugs, TTY keys, Miscellaneous
 @section Interaction with other packages
 @cindex packages, interaction with other
 Org-mode lives in the world of GNU Emacs and interacts in various ways
 with other code out there.
 
 @menu
-* Extensions::                  Third-party extensions for Org-mode
 * Cooperation::                 Packages Org-mode cooperates with
 * Conflicts::                   Packages that lead to conflicts
 @end menu
 
-@node Extensions, Cooperation, Interaction, Interaction
-@subsection Third-party extensions for Org-mode
-
-The following extensions for Org-mode have been written by other people:
-
-@table @asis
-@cindex @file{org-mouse.el}
-@item @file{org-mouse.el} by Piotr Zielinski
-This package implements extended mouse functionality for Org-mode.  It
-allows you to cycle visibility and to edit the document structure with
-the mouse.  Best of all, it provides a context-sensitive menu on
-@key{mouse-3} that changes depending on the context of a mouse-click.
-@file{org-mouse.el} is freely available at @url{http://www.cl.cam.ac.uk/~pz215/files/org-mouse.el}.
-@cindex @file{org-publish.el}
-@item @file{org-publish.el} by David O'Toole
-This package provides facilities for publishing related sets of Org-mode
-files together with linked files like images as a webpages.  It is
-highly configurable and can be used for other publishing purposes as
-well.  As of Org-mode version 4.30, @file{org-publish.el} is part of
-the Org-mode distribution.  It is not yet part of Emacs, however, due to
-a pending copyright assignment.  In the mean time, @file{org-publish.el}
-can be downloaded from David's site:
-@url{http://dto.freeshell.org/e/org-publish.el}.
-@end table
-
-@node Cooperation, Conflicts, Extensions, Interaction
+
+@node Cooperation, Conflicts, Interaction, Interaction
 @subsection Packages that Org-mode cooperates with
 
 @table @asis
@@ -4487,6 +4575,11 @@
 the function @code{constants-get}, which has to be autoloaded in your
 setup.  See the installation instructions in the file
 @file{constants.el}.
+@item @file{cdlatex.el} by Carsten Dominik
+@cindex @file{cdlatex.el}
+Org-mode can make use of the cdlatex package to efficiently enter
+La@TeX{} fragments into Org-mode files.
+@file{cdlatex.el} is not part of Emacs, find it on the web.
 @item @file{remember.el} by John Wiegley
 @cindex @file{remember.el}
 Org mode cooperates with remember, see @ref{Remember}.
@@ -4538,7 +4631,7 @@
 @end table
 
 
-@node Bugs, Acknowledgments, Interaction, Miscellaneous
+@node Bugs,  , Interaction, Miscellaneous
 @section Bugs
 @cindex bugs
 
@@ -4564,10 +4657,6 @@
 (for example because the application does not exist or refuses to open
 the file), it does so silently.  No error message is displayed.
 @item
-Plain list items should be able to hold a TODO item.  Unfortunately this
-has so many technical problems that I will only consider this change for
-the next major release (5.0).
-@item
 The remote-editing commands in the agenda buffer cannot be undone with
 @code{undo} called from within the agenda buffer.  But you can go to
 the corresponding buffer (using @key{TAB} or @key{RET} and execute
@@ -4577,22 +4666,144 @@
 If a formula uses @emph{calculated} fields further down the row,
 multiple recalculation may be needed to get all fields consistent.
 @item
-Several words in a row may @b{*be made bold*}, but this does not work if
-the string is distributed over two lines.
+A single letter cannot be made bold, for example @samp{*a*}.
 @item
 The exporters work well, but could be made more efficient.
 @end itemize
 
-@node Acknowledgments,  , Bugs, Miscellaneous
-@section Acknowledgments
+
+@node Extensions and Hacking, History and Acknowledgments, Miscellaneous, Top
+@appendix Extensions, Hooks and Hacking
+
+This appendix lists extensions for Org-mode written by other authors.
+It also covers some aspects where users can easily extend the
+functionality of Org-mode.
+
+@menu
+* Extensions::                  Existing 3rd-part extensions
+* Dynamic blocks::              Automatically filled blocks
+@end menu
+
+@node Extensions, Dynamic blocks, Extensions and Hacking, Extensions and Hacking
+@section Third-party extensions for Org-mode
+
+The following extensions for Org-mode have been written by other people:
+
+@table @asis
+@cindex @file{org-mouse.el}
+@item @file{org-mouse.el} by Piotr Zielinski
+This package implements extended mouse functionality for Org-mode.  It
+allows you to cycle visibility and to edit the document structure with
+the mouse.  Best of all, it provides a context-sensitive menu on
+@key{mouse-3} that changes depending on the context of a mouse-click.
+@file{org-mouse.el} is freely available at @url{http://www.cl.cam.ac.uk/~pz215/files/org-mouse.el}.
+@cindex @file{org-publish.el}
+@item @file{org-publish.el} by David O'Toole
+This package provides facilities for publishing related sets of Org-mode
+files together with linked files like images as a webpages.  It is
+highly configurable and can be used for other publishing purposes as
+well.  As of Org-mode version 4.30, @file{org-publish.el} is part of the
+Org-mode distribution.  It is not yet part of Emacs, however, a delay
+caused by the preparations for the 22.1 release.  In the mean time,
+@file{org-publish.el} can be downloaded from David's site:
+@url{http://dto.freeshell.org/e/org-publish.el}.
+@cindex @file{org-blog.el}
+@item @file{org-blog.el} by David O'Toole
+A blogging plug-in for @file{org-publish.el}.
+@url{http://dto.freeshell.org/notebook/OrgMode.html}.
+@cindex @file{org-blogging.el}
+@item @file{org-blogging.el} by  Bastien Guerry
+Publish Org-mode files as
+blogs. @url{http://www.cognition.ens.fr/~guerry/org-blogging.html}.
+@end table
+
+@node Dynamic blocks,  , Extensions, Extensions and Hacking
+@section Dynamic blocks
+
+Org-mode documents can contain @emph{dynamic blocks}.  These are
+specially marked regions that are updates by some user-written
+function.  A good example for such a block is the clock table inserted
+by the command @kbd{C-c C-x C-r} (@pxref{Clocking work time}).
+
+Dynamic block are enclosed by a BEGIN-END structure that assigns a name
+to the block and can also specify parameters for the function producing
+the content of the block.
+
+@example
+#+BEGIN: myblock :parameter1 value1 :parameter2 value2 .....
+
+#+END:
+@end example
+
+Dynamic blocks are updated with the following commands
+
+@table @kbd
+@kindex C-c C-x C-u
+@item C-c C-x C-u
+Update dynamic block at point.
+@kindex C-u C-c C-x C-u
+@item C-u C-c C-x C-u
+Update all dynamic blocks in the current file.
+@end table
+
+Updating a dynamic block means to remove all the text between BEGIN and
+END, parse the BEGIN line for parameters and then call the specific
+writer function for this block to insert the new content.  For a block
+with name @code{myblock}, the writer function is
+@code{org-dblock-write:myblock} with as only parameter a property list
+with the parameters given in the begin line.  Here is a trivial example
+of a block that keeps track of when the block update function was last
+run:
+
+@example
+#+BEGIN: block-update-time :format "on %m/%d/%Y at %H:%M"
+
+#+END:
+@end example
+
+@noindent
+The corresponding block writer function could look like this:
+
+@lisp
+(defun org-dblock-write:date-and-time (params)
+   (let ((fmt (or (plist-get params :format) "%d. %m. %Y")))
+     (insert "Last block update at: "
+	     (format-time-string fmt (current-time)))))
+@end lisp
+
+If you want to make sure that all dynamic blocks are always up-to-date,
+you could add the function @code{org-update-all-dblocks} to a hook, for
+example @code{before-save-hook}.  @code{org-update-all-dblocks} is
+written in a way that is does nothing in buffers that are not in Org-mode.
+
+
+@node History and Acknowledgments, Index, Extensions and Hacking, Top
+@appendix History and Acknowledgments
 @cindex acknowledgments
+@cindex history
 @cindex thanks
 
-Org-mode was created by @value{AUTHOR}, who still maintains it at the
-Org-mode homepage @uref{http://www.astro.uva.nl/~dominik/Tools/org/}.
-The following people (in alphabetic order) have helped the development
-along with ideas, suggestions and patches.  Many thanks to all of you,
-Org-mode would not be what it is without your input.
+The beginnings of Org-mode go back to 2003.  It was borne out of
+frustration over the user interface of the emacs outline-mode.  All I
+wanted was to make working with an outline tree possible without having
+to remember more than 10 commands just for hiding and unhiding parts of
+the outline tree, and to allow to restructure a tree easily.  Visibility
+cycling and structure editing were originally implemented in the package
+@file{outline-magic.el}, but quickly moved to the more general
+@file{org.el}.  TODO entries, basic time stamps, and table support were
+added next, and highlight the two main goals that Org-mode still has
+today:  To create a new, outline-based, plain text mode with innovative
+and intuitive editing features, and to incorporate project planning
+functionality directly into a notes file.
+
+Since the first release, hundreds of emails to me or on
+@code{emacs-orgmode@@gnu.org} have provided a constant stream of bug
+reports, feedback, new ideas, and sometimes even patches and add-on
+code.  Many thanks to everyone who has helped to improve this package.
+I am trying to keep here a list of the people who had significant
+influence in shaping one or more aspects of Org-mode.  The list may not
+be complete, if I have forgotten someone, please accept my apologies and
+let me know.
 
 @itemize @bullet
 @item
@@ -4607,8 +4818,9 @@
 @i{Pavel Chalmoviansky} influenced the agenda treatment of items with
 specified time.
 @item
-@i{Gregory Chenov} patched support for lisp forms into table
-calculations and improved XEmacs compatibility.
+@i{Gregory Chernov} patched support for lisp forms into table
+calculations and improved XEmacs compatibility, in particular by porting
+@file{nouline.el} to XEmacs.
 @item
 @i{Sacha Chua} suggested to copy some linking code from Planner.
 @item
@@ -4619,6 +4831,10 @@
 @item
 @i{Nic Ferrier} contributed mailcap and XOXO support.
 @item
+@i{Niels Giessen} had the idea to automatically archive DONE trees.
+@item
+@i{Bastien Guerry} provoded extensive feedback.
+@item
 @i{Kai Grossjohann} pointed out key-binding conflicts caused by
 Org-mode.
 @item
@@ -4656,6 +4872,9 @@
 Linking to VM/BBDB/GNUS was inspired by @i{Tom Shannon}'s
 @file{organizer-mode.el}.
 @item
+@i{Daniel Sinder} came up with the idea of internal archiving my locking
+subtrees.
+@item
 @i{David O'Toole} wrote @file{org-publish.el} and drafted the manual
 chapter about publishing.
 @item
@@ -4684,9 +4903,10 @@
 @i{Piotr Zielinski} wrote @file{org-mouse.el} and showed how to follow
 links with mouse-1.
 @end itemize
- 
-@node Index, Key Index, Miscellaneous, Top
-@chapter Index
+
+
+@node Index, Key Index, History and Acknowledgments, Top
+@unnumbered Index
 
 @printindex cp