From 37755e90aef781d6b14ac2ac9a497f3da92d8739 Mon Sep 17 00:00:00 2001 From: Carsten Dominik Date: Mon, 30 Mar 2009 08:15:28 +0200 Subject: [PATCH] Documentation: Moving section about command line agenda extraction This section is now in the Hacking appendix. --- doc/ChangeLog | 4 + doc/org.texi | 274 ++++++++++++++++++++++++++------------------------ 2 files changed, 149 insertions(+), 129 deletions(-) diff --git a/doc/ChangeLog b/doc/ChangeLog index eb6616b46..3d4b6282b 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,7 @@ +2009-03-30 Carsten Dominik + + * org.texi (Exporting agenda information): Section moved. + 2009-03-27 Carsten Dominik * org.texi (RSS Feeds): New section. diff --git a/doc/org.texi b/doc/org.texi index 6372d8c11..42f2b7ca0 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -254,6 +254,7 @@ Agenda Views * Presentation and sorting:: How agenda items are prepared for display * Agenda commands:: Remote editing of Org trees * Custom agenda views:: Defining special searches and views +* Exporting Agenda Views:: * Agenda column view:: Using column view for collected entries The built-in agenda views @@ -276,8 +277,6 @@ Custom agenda views * Storing searches:: Type once, use often * Block agenda:: All the stuff you need in a single buffer * Setting Options:: Changing the rules -* Exporting Agenda Views:: Writing agendas to files -* Using the agenda elsewhere:: Using agenda information in other programs Embedded LaTeX @@ -392,6 +391,7 @@ Hacking * Tables in arbitrary syntax:: Orgtbl for LaTeX and other programs * Dynamic blocks:: Automatically filled blocks * Special agenda views:: Customized views +* Extracting agenda information:: Postprocessing of agenda information * Using the property API:: Writing programs that use entry properties * Using the mapping API:: Mapping over all or selected entries @@ -2520,7 +2520,6 @@ functions. @end group @end example -@page @node Org Plot, , The spreadsheet, Tables @section Org Plot @cindex graph, in tables @@ -5865,6 +5864,7 @@ window configuration is restored when the agenda exits: * Presentation and sorting:: How agenda items are prepared for display * Agenda commands:: Remote editing of Org trees * Custom agenda views:: Defining special searches and views +* Exporting Agenda Views:: * Agenda column view:: Using column view for collected entries @end menu @@ -7042,7 +7042,7 @@ visit org files will not be removed. @end table -@node Custom agenda views, Agenda column view, Agenda commands, Agenda Views +@node Custom agenda views, Exporting Agenda Views, Agenda commands, Agenda Views @section Custom agenda views @cindex custom agenda views @cindex agenda views, custom @@ -7056,8 +7056,6 @@ dispatcher (@pxref{Agenda dispatcher}), just like the default commands. * Storing searches:: Type once, use often * Block agenda:: All the stuff you need in a single buffer * Setting Options:: Changing the rules -* Exporting Agenda Views:: Writing agendas to files -* Using the agenda elsewhere:: Using agenda information in other programs @end menu @node Storing searches, Block agenda, Custom agenda views, Custom agenda views @@ -7162,7 +7160,7 @@ your agenda for the current week, all TODO items that carry the tag @samp{home}, and also all lines tagged with @samp{garden}. Finally the command @kbd{C-c a o} provides a similar view for office tasks. -@node Setting Options, Exporting Agenda Views, Block agenda, Custom agenda views +@node Setting Options, , Block agenda, Custom agenda views @subsection Setting options for custom commands @cindex options, for custom agenda views @@ -7234,8 +7232,8 @@ value is a string, you need to add the double quotes around the value yourself. -@node Exporting Agenda Views, Using the agenda elsewhere, Setting Options, Custom agenda views -@subsection Exporting Agenda Views +@node Exporting Agenda Views, Agenda column view, Custom agenda views, Agenda Views +@section Exporting Agenda Views @cindex agenda views, exporting If you are away from your computer, it can be very useful to have a printed @@ -7371,110 +7369,12 @@ which will create the agenda views restricted to the file @file{~/org/project.org}, without diary entries and with 30 days extent. -@node Using the agenda elsewhere, , Exporting Agenda Views, Custom agenda views -@subsection Using agenda information outside of Org -@cindex agenda, pipe -@cindex Scripts, for agenda processing +You can also extract agenda information in a way that allows further +processing by other programs. See @ref{Extracting agenda information} for +more information. -@vindex org-agenda-custom-commands -Org provides commands to access agenda information for the command -line in emacs batch mode. This extracted information can be sent -directly to a printer, or it can be read by a program that does further -processing of the data. The first of these commands is the function -@code{org-batch-agenda}, that produces an agenda view and sends it as -ASCII text to STDOUT. The command takes a single string as parameter. -If the string has length 1, it is used as a key to one of the commands -you have configured in @code{org-agenda-custom-commands}, basically any -key you can use after @kbd{C-c a}. For example, to directly print the -current TODO list, you could use -@example -emacs -batch -l ~/.emacs -eval '(org-batch-agenda "t")' | lpr -@end example - -If the parameter is a string with 2 or more characters, it is used as a -tags/todo match string. For example, to print your local shopping list -(all items with the tag @samp{shop}, but excluding the tag -@samp{NewYork}), you could use - -@example -emacs -batch -l ~/.emacs \ - -eval '(org-batch-agenda "+shop-NewYork")' | lpr -@end example - -@noindent -You may also modify parameters on the fly like this: - -@example -emacs -batch -l ~/.emacs \ - -eval '(org-batch-agenda "a" \ - org-agenda-ndays 30 \ - org-agenda-include-diary nil \ - org-agenda-files (quote ("~/org/project.org")))' \ - | lpr -@end example - -@noindent -which will produce a 30 day agenda, fully restricted to the Org file -@file{~/org/projects.org}, not even including the diary. - -If you want to process the agenda data in more sophisticated ways, you -can use the command @code{org-batch-agenda-csv} to get a comma-separated -list of values for each agenda item. Each line in the output will -contain a number of fields separated by commas. The fields in a line -are: - -@example -category @r{The category of the item} -head @r{The headline, without TODO kwd, TAGS and PRIORITY} -type @r{The type of the agenda entry, can be} - todo @r{selected in TODO match} - tagsmatch @r{selected in tags match} - diary @r{imported from diary} - deadline @r{a deadline} - scheduled @r{scheduled} - timestamp @r{appointment, selected by timestamp} - closed @r{entry was closed on date} - upcoming-deadline @r{warning about nearing deadline} - past-scheduled @r{forwarded scheduled item} - block @r{entry has date block including date} -todo @r{The TODO keyword, if any} -tags @r{All tags including inherited ones, separated by colons} -date @r{The relevant date, like 2007-2-14} -time @r{The time, like 15:00-16:50} -extra @r{String with extra planning info} -priority-l @r{The priority letter if any was given} -priority-n @r{The computed numerical priority} -@end example - -@noindent -Time and date will only be given if a timestamp (or deadline/scheduled) -lead to the selection of the item. - -A CSV list like this is very easy to use in a post processing script. -For example, here is a Perl program that gets the TODO list from -Emacs/Org and prints all the items, preceded by a checkbox: - -@example -#!/usr/bin/perl - -# define the Emacs command to run -$cmd = "emacs -batch -l ~/.emacs -eval '(org-batch-agenda-csv \"t\")'"; - -# run it and capture the output -$agenda = qx@{$cmd 2>/dev/null@}; - -# loop over all lines -foreach $line (split(/\n/,$agenda)) @{ - # get the individual values - ($category,$head,$type,$todo,$tags,$date,$time,$extra, - $priority_l,$priority_n) = split(/,/,$line); - # process and print - print "[ ] $head\n"; -@} -@end example - -@node Agenda column view, , Custom agenda views, Agenda Views +@node Agenda column view, , Exporting Agenda Views, Agenda Views @section Using column view in the agenda @cindex column view, in agenda @cindex agenda, column view @@ -9095,21 +8995,20 @@ Export only the visible part of the document. @vindex org-icalendar-use-deadline @vindex org-icalendar-use-scheduled @vindex org-icalendar-categories -Some people like to use Org mode for keeping track of projects, but still -prefer a standard calendar application for anniversaries and appointments. -In this case it can be useful to have deadlines and other time-stamped items -in Org files show up in the calendar application. Org mode can export -calendar information in the standard iCalendar format. If you also want to -have TODO entries included in the export, configure the variable -@code{org-icalendar-include-todo}. iCalendar export will export plain time -stamps as VEVENT, and TODO items as VTODO. It will also create events from -deadlines that are in non-TODO items. Deadlines and scheduling dates in TODO -items will be used to set the start and due dates for the todo -entry@footnote{See the variables @code{org-icalendar-use-deadline} and -@code{org-icalendar-use-scheduled}.}. As categories, it will use the tags -locally defined in the heading, and the file/tree category@footnote{To add -inherited tags or the TODO state, configure the variable -@code{org-icalendar-categories}.}. +Some people use Org mode for keeping track of projects, but still prefer a +standard calendar application for anniversaries and appointments. In this +case it can be useful to show deadlines and other time-stamped items in Org +files in the calendar application. Org mode can export calendar information +in the standard iCalendar format. If you also want to have TODO entries +included in the export, configure the variable +@code{org-icalendar-include-todo}. Plain time stamps are exported as VEVENT, +and TODO items as VTODO. It will also create events from deadlines that are +in non-TODO items. Deadlines and scheduling dates in TODO items will be used +to set the start and due dates for the todo entry@footnote{See the variables +@code{org-icalendar-use-deadline} and @code{org-icalendar-use-scheduled}.}. +As categories, it will use the tags locally defined in the heading, and the +file/tree category@footnote{To add inherited tags or the TODO state, +configure the variable @code{org-icalendar-categories}.}. @vindex org-icalendar-store-UID The iCalendar standard requires each entry to have a globally unique @@ -9161,7 +9060,7 @@ Org includes a publishing management system that allows you to configure automatic HTML conversion of @emph{projects} composed of interlinked org files. You can also configure Org to automatically upload your exported HTML pages and related attachments, such as images and source code files, to a web -server. With htese features, Org becomes a web-site authoring tool. +server. You can also use Org to convert files into PDF, or even combine HTML and PDF conversion so that files are available in both formats on the server. @@ -10244,6 +10143,7 @@ Org. * Tables in arbitrary syntax:: Orgtbl for LaTeX and other programs * Dynamic blocks:: Automatically filled blocks * Special agenda views:: Customized views +* Extracting agenda information:: Postprocessing of agenda information * Using the property API:: Writing programs that use entry properties * Using the mapping API:: Mapping over all or selected entries @end menu @@ -10797,7 +10697,7 @@ 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 @code{org-mode}. -@node Special agenda views, Using the property API, Dynamic blocks, Hacking +@node Special agenda views, Extracting agenda information, Dynamic blocks, Hacking @section Special agenda views @cindex agenda views, user-defined @@ -10886,7 +10786,123 @@ like this, even without defining a special function: (org-agenda-overriding-header "Projects waiting for something: ")))) @end lisp -@node Using the property API, Using the mapping API, Special agenda views, Hacking +@node Extracting agenda information, Using the property API, Special agenda views, Hacking +@section Extracting agenda information +@cindex agenda, pipe +@cindex Scripts, for agenda processing + +@vindex org-agenda-custom-commands +Org provides commands to access agenda information for the command +line in emacs batch mode. This extracted information can be sent +directly to a printer, or it can be read by a program that does further +processing of the data. The first of these commands is the function +@code{org-batch-agenda}, that produces an agenda view and sends it as +ASCII text to STDOUT. The command takes a single string as parameter. +If the string has length 1, it is used as a key to one of the commands +you have configured in @code{org-agenda-custom-commands}, basically any +key you can use after @kbd{C-c a}. For example, to directly print the +current TODO list, you could use + +@example +emacs -batch -l ~/.emacs -eval '(org-batch-agenda "t")' | lpr +@end example + +If the parameter is a string with 2 or more characters, it is used as a +tags/todo match string. For example, to print your local shopping list +(all items with the tag @samp{shop}, but excluding the tag +@samp{NewYork}), you could use + +@example +emacs -batch -l ~/.emacs \ + -eval '(org-batch-agenda "+shop-NewYork")' | lpr +@end example + +@noindent +You may also modify parameters on the fly like this: + +@example +emacs -batch -l ~/.emacs \ + -eval '(org-batch-agenda "a" \ + org-agenda-ndays 30 \ + org-agenda-include-diary nil \ + org-agenda-files (quote ("~/org/project.org")))' \ + | lpr +@end example + +@noindent +which will produce a 30 day agenda, fully restricted to the Org file +@file{~/org/projects.org}, not even including the diary. + +If you want to process the agenda data in more sophisticated ways, you +can use the command @code{org-batch-agenda-csv} to get a comma-separated +list of values for each agenda item. Each line in the output will +contain a number of fields separated by commas. The fields in a line +are: + +@example +category @r{The category of the item} +head @r{The headline, without TODO kwd, TAGS and PRIORITY} +type @r{The type of the agenda entry, can be} + todo @r{selected in TODO match} + tagsmatch @r{selected in tags match} + diary @r{imported from diary} + deadline @r{a deadline} + scheduled @r{scheduled} + timestamp @r{appointment, selected by timestamp} + closed @r{entry was closed on date} + upcoming-deadline @r{warning about nearing deadline} + past-scheduled @r{forwarded scheduled item} + block @r{entry has date block including date} +todo @r{The TODO keyword, if any} +tags @r{All tags including inherited ones, separated by colons} +date @r{The relevant date, like 2007-2-14} +time @r{The time, like 15:00-16:50} +extra @r{String with extra planning info} +priority-l @r{The priority letter if any was given} +priority-n @r{The computed numerical priority} +@end example + +@noindent +Time and date will only be given if a timestamp (or deadline/scheduled) +lead to the selection of the item. + +A CSV list like this is very easy to use in a post processing script. +For example, here is a Perl program that gets the TODO list from +Emacs/Org and prints all the items, preceded by a checkbox: + +@example +#!/usr/bin/perl + +# define the Emacs command to run +$cmd = "emacs -batch -l ~/.emacs -eval '(org-batch-agenda-csv \"t\")'"; + +# run it and capture the output +$agenda = qx@{$cmd 2>/dev/null@}; + +# loop over all lines +foreach $line (split(/\n/,$agenda)) @{ + # get the individual values + ($category,$head,$type,$todo,$tags,$date,$time,$extra, + $priority_l,$priority_n) = split(/,/,$line); + # process and print + print "[ ] $head\n"; +@} +@end example + + + + + + + + + + + + + + +@node Using the property API, Using the mapping API, Extracting agenda information, Hacking @section Using the property API @cindex API, for properties @cindex properties, API