+@node Radio tables, A LaTeX example, Tables in arbitrary syntax, Tables in arbitrary syntax
+@subsection Radio tables
+@cindex radio tables
+
+To define the location of the target table, you first need to create two
+lines that are comments in the current mode, but contain magic words for
+Orgtbl-mode to find. Orgtbl-mode will insert the translated table
+between these lines, replacing whatever was there before. For example:
+
+@example
+/* BEGIN RECEIVE ORGTBL table_name */
+/* END RECEIVE ORGTBL table_name */
+@end example
+
+@noindent
+Just above the source table, we put a special line that tells
+Orgtbl-mode how to translate this table and where to install it. For
+example:
+@example
+#+ORGTBL: SEND table_name translation_function arguments....
+@end example
+
+@noindent
+@code{table_name} is the reference name for the table that is also used
+in the receiver lines. @code{translation_function} is the Lisp function
+that does the translation. Furthermore, the line can contain a list of
+arguments (alternating key and value) at the end. The arguments will be
+passed as a property list to the translation function for
+interpretation. A few standard parameters are already recognized and
+acted upon before the translation function is called:
+
+@table @code
+@item :skip N
+Skip the first N lines of the table. Hlines do count!
+@item :skipcols (n1 n2 ...)
+List of columns that should be skipped. If the table has a column with
+calculation marks, that column is automatically discarded as well.
+Please note that the translator function sees the table @emph{after} the
+removal of these columns, the function never knows that there have been
+additional columns.
+@end table
+
+@noindent
+The one problem remaining is how to keep the source table in the buffer
+without disturbing the normal workings of the file, for example during
+compilation of a C file or processing of a LaTeX file. There are a
+number of different solutions:
+
+@itemize @bullet
+@item
+The table could be placed in a block comment if that is supported by the
+language. For example, in C-mode you could wrap the table between
+@samp{/*} and @samp{*/} lines.
+@item
+Sometimes it is possible to put the table after some kind of @i{END}
+statement, for example @samp{\bye} in TeX and @samp{\end@{document@}}
+in LaTeX.
+@item
+You can just comment the table line by line whenever you want to process
+the file, and uncomment it whenever you need to edit the table. This
+only sounds tedious - the command @kbd{M-x orgtbl-toggle-comment} does
+make this comment-toggling very easy, in particular if you bind it to a
+key.
+@end itemize
+
+@node A LaTeX example, Translator functions, Radio tables, Tables in arbitrary syntax
+@subsection A LaTeX example
+@cindex LaTeX, and orgtbl-mode
+
+The best way to wrap the source table in LaTeX is to use the
+@code{comment} environment provided by @file{comment.sty}. It has to be
+activated by placing @code{\usepackage@{comment@}} into the document
+header. Orgtbl-mode can insert a radio table skeleton@footnote{By
+default this works only for LaTeX, HTML, and TeXInfo. Configure the
+variable @code{orgtbl-radio-tables} to install templates for other
+modes.} with the command @kbd{M-x orgtbl-insert-radio-table}. You will
+be prompted for a table name, lets say we use @samp{salesfigures}. You
+will then get the following template:
+
+@example
+% BEGIN RECEIVE ORGTBL salesfigures
+% END RECEIVE ORGTBL salesfigures
+\begin@{comment@}
+#+ORGTBL: SEND salesfigures orgtbl-to-latex
+| | |
+\end@{comment@}
+@end example
+
+@noindent
+The @code{#+ORGTBL: SEND} line tells orgtbl-mode to use the function
+@code{orgtbl-to-latex} to convert the table into LaTeX and to put it
+into the receiver location with name @code{salesfigures}. You may now
+fill in the table, feel free to use the spreadsheet features@footnote{If
+the @samp{#+TBLFM} line contains an odd number of dollar characters,
+this may cause problems with font-lock in latex-mode. As shown in the
+example you can fix this by adding an extra line inside the
+@code{comment} environment that is used to balance the dollar
+expressions. If you are using AUCTeX with the font-latex library, a
+much better solution is to add the @code{comment} environment to the
+variable @code{LaTeX-verbatim-environments}.}:
+
+@example
+% BEGIN RECEIVE ORGTBL salesfigures
+% END RECEIVE ORGTBL salesfigures
+\begin@{comment@}
+#+ORGTBL: SEND salesfigures orgtbl-to-latex
+| Month | Days | Nr sold | per day |
+|-------+------+---------+---------|
+| Jan | 23 | 55 | 2.4 |
+| Feb | 21 | 16 | 0.8 |
+| March | 22 | 278 | 12.6 |
+#+TBLFM: $4=$3/$2;%.1f
+% $ (optional extra dollar to keep font-lock happy, see footnote)
+\end@{comment@}
+@end example
+
+@noindent
+When you are done, press @kbd{C-c C-c} in the table to get the converted
+table inserted between the two marker lines.
+
+Now lets assume you want to make the table header by hand, because you
+want to control how columns are aligned etc. In this case we make sure
+that the table translator does skip the first 2 lines of the source
+table, and tell the command to work as a @i{splice}, i.e. to not produce
+header and footer commands of the target table:
+
+@example
+\begin@{tabular@}@{lrrr@}
+Month & \multicolumn@{1@}@{c@}@{Days@} & Nr.\ sold & per day\\
+% BEGIN RECEIVE ORGTBL salesfigures
+% END RECEIVE ORGTBL salesfigures
+\end@{tabular@}
+%
+\begin@{comment@}
+#+ORGTBL: SEND salesfigures orgtbl-to-latex :splice t :skip 2
+| Month | Days | Nr sold | per day |
+|-------+------+---------+---------|
+| Jan | 23 | 55 | 2.4 |
+| Feb | 21 | 16 | 0.8 |
+| March | 22 | 278 | 12.6 |
+#+TBLFM: $4=$3/$2;%.1f
+\end@{comment@}
+@end example
+
+The LaTeX translator function @code{orgtbl-to-latex} is already part of
+Orgtbl-mode. It uses a @code{tabular} environment to typeset the table
+and marks horizontal lines with @code{\hline}. Furthermore, it
+interprets the following parameters:
+
+@table @code
+@item :splice nil/t
+When set to t, return only table body lines, don't wrap them into a
+tabular environment. Default is nil.
+
+@item :fmt fmt
+A format to be used to wrap each field, should contain @code{%s} for the
+original field value. For example, to wrap each field value in dollars,
+you could use @code{:fmt "$%s$"}. This may also be a property list with
+column numbers and formats. for example @code{:fmt (2 "$%s$" 4 "%s\\%%")}.
+
+@item :efmt efmt
+Use this format to print numbers with exponentials. The format should
+have @code{%s} twice for inserting mantissa and exponent, for example
+@code{"%s\\times10^@{%s@}"}. The default is @code{"%s\\,(%s)"}. This
+may also be a property list with column numbers and formats, for example
+@code{:efmt (2 "$%s\\times10^@{%s@}$" 4 "$%s\\cdot10^@{%s@}$")}. After
+@code{efmt} has been applied to a value, @code{fmt} will also be
+applied.
+@end table
+
+@node Translator functions, , A LaTeX example, Tables in arbitrary syntax
+@subsection Translator functions
+@cindex HTML, and orgtbl-mode
+@cindex translator function
+
+Orgtbl-mode has several translator functions built-in:
+@code{orgtbl-to-latex}, @code{orgtbl-to-html}, and
+@code{orgtbl-to-texinfo}. Except for @code{orgtbl-to-html}@footnote{The
+HTML translator uses the same code that produces tables during HTML
+export.}, these all use a generic translator, @code{orgtbl-to-generic}.
+For example, @code{orgtbl-to-latex} itself is a very short function that
+computes the column definitions for the @code{tabular} environment,
+defines a few field and line separators and then hands over to the
+generic translator. Here is the entire code:
+
+@lisp
+@group
+(defun orgtbl-to-latex (table params)
+ "Convert the orgtbl-mode TABLE to LaTeX."
+ (let* ((alignment (mapconcat (lambda (x) (if x "r" "l"))
+ org-table-last-alignment ""))
+ (params2
+ (list
+ :tstart (concat "\\begin@{tabular@}@{" alignment "@}")
+ :tend "\\end@{tabular@}"
+ :lstart "" :lend " \\\\" :sep " & "
+ :efmt "%s\\,(%s)" :hline "\\hline")))
+ (orgtbl-to-generic table (org-combine-plists params2 params))))
+@end group
+@end lisp
+
+As you can see, the properties passed into the function (variable
+@var{PARAMS}) are combined with the ones newly defined in the function
+(variable @var{PARAMS2}). The ones passed into the function (i.e. the
+ones set by the @samp{ORGTBL SEND} line) take precedence. So if you
+would like to use the LaTeX translator, but wanted the line endings to
+be @samp{\\[2mm]} instead of the default @samp{\\}, you could just
+overrule the default with
+
+@example
+#+ORGTBL: SEND test orgtbl-to-latex :lend " \\\\[2mm]"
+@end example
+
+For a new language, you can either write your own converter function in
+analogy with the LaTeX translator, or you can use the generic function
+directly. For example, if you have a language where a table is started
+with @samp{!BTBL!}, ended with @samp{!ETBL!}, and where table lines are
+started with @samp{!BL!}, ended with @samp{!EL!} and where the field
+separator is a TAB, you could call the generic translator like this (on
+a single line!):
+
+@example
+#+ORGTBL: SEND test orgtbl-to-generic :tstart "!BTBL!" :tend "!ETBL!"
+ :lstart "!BL! " :lend " !EL!" :sep "\t"
+@end example
+
+@noindent
+Please check the documentation string of the function
+@code{orgtbl-to-generic} for a full list of parameters understood by
+that function and remember that you can pass each of them into
+@code{orgtbl-to-latex}, @code{orgtbl-to-texinfo}, and any other function
+using the generic function.
+
+Of course you can also write a completely new function doing complicated
+things the generic translator cannot do. A translator function takes
+two arguments. The first argument is the table, a list of lines, each
+line either the symbol @code{hline} or a list of fields. The second
+argument is the property list containing all parameters specified in the
+@samp{#+ORGTBL: SEND} line. The function must return a single string
+containing the formatted table. If you write a generally useful
+translator, please post it on @code{emacs-orgmode@@gnu.org} so that
+others can benefit from your work.
+
+@node Dynamic blocks, Special agenda views, Tables in arbitrary syntax, Extensions and Hacking
+@section Dynamic blocks
+@cindex dynamic blocks
+
+Org-mode documents can contain @emph{dynamic blocks}. These are
+specially marked regions that are updated 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:block-update-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 Special agenda views, , Dynamic blocks, Extensions and Hacking
+@section Special Agenda Views
+@cindex agenda views, user-defined
+
+Org-mode provides a special hook that can be used to narrow down the
+selection made by any of the agenda views. You may specify a function
+that is used at each match to verify if the match should indeed be part
+of the agenda view, and if not, how much should be skipped.
+
+Let's say you want to produce a list of projects that contain a WAITING
+tag anywhere in the project tree. Let's further assume that you have
+marked all tree headings that define a project with the todo keyword
+PROJECT. In this case you would run a todo search for the keyword
+PROJECT, but skip the match unless there is a WAITING tag anywhere in
+the subtree belonging to the project line.
+
+To achieve this, you must write a function that searches the subtree for
+the tag. If the tag is found, the function must return @code{nil} to
+indicate that this match should not be skipped. If there is no such
+tag, return the location of the end of the subtree, to indicate that
+search should continue from there.
+
+@lisp
+(defun my-skip-unless-waiting ()
+ "Skip trees that are not waiting"
+ (let ((subtree-end (save-excursion (org-end-of-subtree t))))
+ (if (re-search-forward ":WAITING:" subtree-end t)
+ nil ; tag found, do not skip
+ subtree-end))) ; tag not found, continue after end of subtree
+@end lisp
+
+Furthermore you must write a command that uses @code{let} to temporarily
+put this function into the variable @code{org-agenda-skip-function},
+sets the header string for the agenda buffer, and calls the todo-list
+generator while asking for the specific TODO keyword PROJECT. The
+function must also accept one argument MATCH, but it can choose to
+ignore it@footnote{MATCH must be present in case you want to define a
+custom command for producing this special list. Custom commands always
+supply the MATCH argument, but it can be empty if you do not specify it
+while defining the command(@pxref{Custom agenda
+views}).} (as we do in the example below). Here is the example:
+
+@lisp
+(defun my-org-waiting-projects (&optional match)
+ "Produce a list of projects that contain a WAITING tag.
+MATCH is being ignored."
+ (interactive)
+ (let ((org-agenda-skip-function 'my-skip-unless-waiting)
+ (org-agenda-overriding-header "Projects waiting for something: "))
+ ;; make the list
+ (org-todo-list "PROJECT")))
+@end lisp
+
+
+@node History and Acknowledgments, Index, Extensions and Hacking, Top
+@appendix History and Acknowledgments
+@cindex acknowledgments
+@cindex history
+@cindex thanks
+
+Org-mode was borne in 2003, out of frustration over the user interface
+of the Emacs outline-mode. I was trying to organize my notes and
+projects, and using Emacs seemed to be the natural way to go. However,
+having to remember eleven different commands with two or three keys per
+command, only to hide and unhide parts of the outline tree, that seemed
+entirely unacceptable to me. Also, when using outlines to take notes, I
+constantly want to restructure the tree, organizing it parallel to my
+thoughts and plans. @emph{Visibility cycling} and @emph{structure
+editing} were originally implemented in the package
+@file{outline-magic.el}, but quickly moved to the more general
+@file{org.el}. As this environment became comfortable for project
+planning, the next step was adding @emph{TODO entries}, basic @emph{time
+stamps}, and @emph{table support}. These areas 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 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.