diff --git a/org b/org index d1331b876..73510d128 100644 --- a/org +++ b/org @@ -5,7 +5,7 @@ START-INFO-DIR-ENTRY * Org Mode: (org). outline-based notes management and organizer END-INFO-DIR-ENTRY - This manual is for Org-mode (version 4.60). + This manual is for Org-mode (version 4.61). Copyright (C) 2004, 2005, 2006 Free Software Foundation @@ -27,7 +27,7 @@ File: org, Node: Top, Next: Introduction, Prev: (dir), Up: (dir) Org Mode Manual *************** -This manual is for Org-mode (version 4.60). +This manual is for Org-mode (version 4.61). Copyright (C) 2004, 2005, 2006 Free Software Foundation @@ -140,6 +140,7 @@ Timestamps * Time stamps:: Assigning a time to a tree entry * Creating timestamps:: Commands which insert timestamps * Custom time format:: If you cannot work with the ISO format +* Repeating items:: * Progress logging:: Documenting when what work was done. Creating timestamps @@ -748,11 +749,11 @@ 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. -`C-c $' +`C-c C-x C-s' Archive the subtree starting at the cursor position to the location given by `org-archive-location'. -`C-u C-c $' +`C-u C-c C-x C-s' 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 @@ -763,6 +764,13 @@ file, the archive file. current file, with the name derived by appending `_archive' to the current file name. For information and examples on how to change this, see the documentation string of the variable `org-archive-location'. +There is also an in-buffer option for setting this variable, for example + + #+ARCHIVE: %s_done:: + +You may have several such lines in the buffer, they will then be valid +for the entries following the line (the first will also apply to any +text before it).  File: org, Node: Sparse trees, Next: Plain lists, Prev: Archiving, Up: Document structure @@ -1084,7 +1092,8 @@ Calculations `C-c '' Edit all formulas associated with the current table in a separate - buffer. + buffer. Use `C-u C-u C-c =' to edit the formula directly in the + current field, to allow checking complex references with `C-c ?'. `C-c *' Recalculate the current row by applying the stored formulas from @@ -1100,8 +1109,9 @@ Calculations marks in the region. `C-c ?' - Which table column is the cursor in? Displays number >0 in echo - area. + Display line and column number of current field in echo area. If + the cursor is currently editing a formula, the field or range + referenced by the expression at point will be highlighted. `C-c +' Sum the numbers in the current column, or in the rectangle defined @@ -2311,6 +2321,7 @@ planning. * Time stamps:: Assigning a time to a tree entry * Creating timestamps:: Commands which insert timestamps * Custom time format:: If you cannot work with the ISO format +* Repeating items:: Deadlines that come back again and again * Progress logging:: Documenting when what work was done.  @@ -2540,7 +2551,7 @@ can control the calendar fully from the minibuffer: `org-popup-calendar-for-date-prompt'.  -File: org, Node: Custom time format, Next: Progress logging, Prev: Creating timestamps, Up: Timestamps +File: org, Node: Custom time format, Next: Repeating items, Prev: Creating timestamps, Up: Timestamps 6.3 Custom time format ====================== @@ -2576,9 +2587,48 @@ consequences: the custom format is shorter, things do work as expected.  -File: org, Node: Progress logging, Prev: Custom time format, Up: Timestamps +File: org, Node: Repeating items, Next: Progress logging, Prev: Custom time format, Up: Timestamps -6.4 Progress Logging +6.4 Repeating items +=================== + +Org-mode integrates with the Emacs calendar and diary to display cyclic +appointments, anniversaries and other special entries in the agenda +(*note Weekly/Daily agenda::). However, it can be useful to have +certain deadlines and scheduling items to auto-repeat. The advantage of +a deadline or scheduled item is that the they produce warnings ahead of +time and automatically forward themselves in the agenda until they are +done. The abstract difference is therefore between cyclic appointments +and cyclic action items. For appointments you should use the diary, +for actions you can uses an org-mode deadline or scheduling time stamp +together with a REPEAT cookie. For example: + + * TODO Replace batteries in smoke detector REPEAT(+18m) + SCHEDULED: <2007-01-01 Mon> + + * TODO Get dentist appointment REPEAT(+6m) + SCHEDULED: <2006-12-19 Tue> + + * TODO Tax report to IRS REPEAT(+1y) + DEADLINE: <2007-04-01 Sun> + + Each time you try to mark one of these entries DONE using `C-c C-t', +they will automatically switch back to the state TODO, and the +deadline/scheduling will be shifted accordingly. The time units +recognized by org-mode are year (y), month (m), week (w), and day (d). +Org-mode will also prompt you for a note and record the fact that you +have closed this item in a note under the headline. + + One unusual property of these repeating items is that only one +instance of each exist at any given time. So if you look back or ahead +in the agenda, you will not find past and future instances, only the +current one will show up. Use a cyclic diary entry if you need all +past and future instances to be visible in the angenda. + + +File: org, Node: Progress logging, Prev: Repeating items, Up: Timestamps + +6.5 Progress Logging ==================== Org-mode can automatically record a time stamp when you mark a TODO item @@ -2596,7 +2646,7 @@ on an aspect of a project.  File: org, Node: Closing items, Next: Tracking TODO state changes, Prev: Progress logging, Up: Progress logging -6.4.1 Closing items +6.5.1 Closing items ------------------- If you want to keep track of _when_ a certain TODO item was finished, @@ -2625,7 +2675,7 @@ the timestamp, use(2)  File: org, Node: Tracking TODO state changes, Next: Clocking work time, Prev: Closing items, Up: Progress logging -6.4.2 Tracking TODO state changes +6.5.2 Tracking TODO state changes --------------------------------- When TODO keywords are used as workflow states (*note Workflow @@ -2647,7 +2697,7 @@ these into a separate file that starts with:  File: org, Node: Clocking work time, Prev: Tracking TODO state changes, Up: Progress logging -6.4.3 Clocking work time +6.5.3 Clocking work time ------------------------ Org-mode allows you to clock the time you spent on specific tasks in a @@ -4866,7 +4916,15 @@ file is visited again in a new Emacs session. `#+CATEGORY:' This line sets the category for the agenda file. The category applies for all subsequent lines until the next `#+CATEGORY' line, - or the end of the file. + or the end of the file. The first such line also applies to any + entries before it. + +`#+ARCHIVE: %s_done::' + This line sets the archive location for the agenda file. It + applies for all subsequent lines until the next `#+CATEGORY' line, + or the end of the file. The first such line also applies to any + entries before it. The correspoinding variable is + `org-archive-location'. `#+TBLFM:' This line contains the formulas for the table directly above the @@ -5219,9 +5277,13 @@ The following extensions for Org-mode have been written by other people: A blogging plug-in for `org-publish.el'. `http://dto.freeshell.org/notebook/OrgMode.html'. -`blorg.el' by Bastien Guerry +`blorg.el' by Bastien Guerry Publish Org-mode files as blogs. - `http://www.cognition.ens.fr/~guerry/blorg.html'. + `http://www.cognition.ens.fr/~guerry/blorg.html'. + +`org2rem.el' by Bastien Guerry + Translates Org-mode files into something readable by Remind. + `http://www.cognition.ens.fr/~guerry/u/org2rem.el'.  File: org, Node: Dynamic blocks, Next: Special agenda views, Prev: Extensions, Up: Extensions and Hacking @@ -5349,7 +5411,7 @@ incorporate project planning functionality directly into a notes file. Since the first release, hundreds of emails to me or on `emacs-orgmode@gnu.org' have provided a constant stream of bug reports, -feedback, new ideas, and sometimes even patches and add-on code. Many +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, @@ -5387,11 +5449,14 @@ if I have forgotten someone, please accept my apologies and let me know. * Niels Giessen had the idea to automatically archive DONE trees. - * Bastien Guerry provided extensive feedback. + * Bastien Guerry provided extensive feedback and some patches, and + translated David O'Toole's tutorial into French. * Kai Grossjohann pointed out key-binding conflicts with other packages. + * Shidai Liu ("Leo") provided extensive feedback and some patches. + * Leon Liu asked for embedded LaTeX and tested it. * Stefan Monnier provided a patch to keep the Emacs-Lisp compiler @@ -5402,6 +5467,9 @@ if I have forgotten someone, please accept my apologies and let me know. * Tim O'Callaghan suggested in-file links, search options for general file links, and TAGS. + * Takeshi Okano translated the manual and David O'Toole's tutorial + into Japanese. + * Oliver Oppitz suggested multi-state TODO items. * Scott Otterson sparked the introduction of descriptive text for @@ -5481,7 +5549,7 @@ Index * active region <1>: Export commands. (line 6) * active region <2>: ASCII export. (line 9) * active region <3>: Built-in table editor. - (line 171) + (line 173) * active region: Structure editing. (line 64) * agenda: Weekly/Daily agenda. (line 6) * agenda dispatcher: Agenda dispatcher. (line 6) @@ -5570,6 +5638,7 @@ Index (line 6) * DEADLINE keyword: Time stamps. (line 53) * deadlines: Time stamps. (line 6) +* Deadlines, repeating: Repeating items. (line 6) * demotion, of subtrees: Structure editing. (line 6) * diary entries, creating from agenda: Agenda commands. (line 198) * diary integration: Weekly/Daily agenda. (line 24) @@ -5716,6 +5785,7 @@ Index * org-mouse.el: Extensions. (line 17) * org-publish-project-alist: Project alist. (line 6) * org-publish.el: Extensions. (line 8) +* org2rem.el: Extensions. (line 37) * orgtbl-mode: orgtbl-mode. (line 6) * outline tree: Headlines. (line 6) * outline-mode: Outlines. (line 6) @@ -5744,7 +5814,7 @@ Index * region, active <1>: Export commands. (line 6) * region, active <2>: ASCII export. (line 9) * region, active <3>: Built-in table editor. - (line 171) + (line 173) * region, active: Structure editing. (line 64) * regular expressions, with tags search: Tag searches. (line 63) * remember.el <1>: Cooperation. (line 33) @@ -5755,6 +5825,7 @@ Index * RMAIL links: External links. (line 6) * SCHEDULED keyword: Time stamps. (line 40) * scheduling: Time stamps. (line 6) +* Scheduling, repeating: Repeating items. (line 6) * search option in file links: Search options. (line 6) * search strings, custom: Custom searches. (line 6) * searching for tags: Tag searches. (line 6) @@ -5834,6 +5905,7 @@ Index * timestamp, inactive: Time stamps. (line 24) * timestamps, creating: Creating timestamps. (line 6) * TODO items: TODO items. (line 6) +* TODO items, repeating: Repeating items. (line 6) * TODO keyword matching: Global TODO list. (line 17) * TODO keyword matching, with tags search: Tag searches. (line 40) * TODO keywords completion: Completion. (line 6) @@ -5843,7 +5915,7 @@ Index * transient-mark-mode <1>: Export commands. (line 6) * transient-mark-mode <2>: ASCII export. (line 9) * transient-mark-mode <3>: Built-in table editor. - (line 171) + (line 173) * transient-mark-mode: Structure editing. (line 64) * trees, sparse: Sparse trees. (line 6) * trees, visibility: Visibility cycling. (line 6) @@ -5911,13 +5983,12 @@ Key Index * C: Agenda commands. (line 213) * c: Agenda commands. (line 191) * C-#: Built-in table editor. - (line 161) + (line 162) * C-,: Agenda files. (line 18) * C-_: Agenda commands. (line 109) * C-a a L: Timeline. (line 10) * C-c !: Creating timestamps. (line 21) * C-c #: Checkboxes. (line 56) -* C-c $: Moving subtrees. (line 10) * C-c %: Handling links. (line 81) * C-c &: Handling links. (line 85) * C-c ' <1>: Editing/debugging formulas. @@ -5925,9 +5996,9 @@ Key Index * C-c ': Built-in table editor. (line 150) * C-c *: Built-in table editor. - (line 154) + (line 155) * C-c +: Built-in table editor. - (line 171) + (line 173) * C-c ,: Priorities. (line 18) * C-c -: Built-in table editor. (line 92) @@ -5937,14 +6008,14 @@ Key Index * C-c ;: Comment lines. (line 11) * C-c <: Creating timestamps. (line 25) * C-c : Built-in table editor. - (line 193) + (line 195) * C-c =: Built-in table editor. (line 141) * C-c >: Creating timestamps. (line 29) * C-c ? <1>: Editing/debugging formulas. (line 20) * C-c ?: Built-in table editor. - (line 167) + (line 168) * C-c [: Agenda files. (line 12) * C-c \: Tag searches. (line 9) * C-c ]: Agenda files. (line 15) @@ -5952,7 +6023,7 @@ Key Index (line 96) * C-c ^: Structure editing. (line 52) * C-c `: Built-in table editor. - (line 187) + (line 189) * C-c a !: Stuck projects. (line 14) * C-c a #: Stuck projects. (line 13) * C-c a a: Weekly/Daily agenda. (line 9) @@ -6026,6 +6097,7 @@ Key Index (line 9) * C-c C-x C-o: Clocking work time. (line 14) * C-c C-x C-r: Clocking work time. (line 43) +* C-c C-x C-s: Moving subtrees. (line 10) * C-c C-x C-t: Custom time format. (line 12) * C-c C-x C-u: Dynamic blocks. (line 21) * C-c C-x C-w <1>: Built-in table editor. @@ -6047,12 +6119,12 @@ Key Index * C-c ~: table.el. (line 18) * C-k: Agenda commands. (line 117) * C-TAB: ARCHIVE tag. (line 38) -* C-u C-c $: Moving subtrees. (line 12) * C-u C-c .: Creating timestamps. (line 16) * C-u C-c =: Built-in table editor. (line 145) * C-u C-c C-l: Handling links. (line 43) * C-u C-c C-x C-a: ARCHIVE tag. (line 31) +* C-u C-c C-x C-s: Moving subtrees. (line 12) * C-u C-c C-x C-u <1>: Dynamic blocks. (line 22) * C-u C-c C-x C-u: Clocking work time. (line 70) * D: Agenda commands. (line 74) @@ -6133,7 +6205,7 @@ Key Index * S- <3>: Creating timestamps. (line 53) * S-: TODO basics. (line 20) * S-: Built-in table editor. - (line 176) + (line 178) * S- <1>: Agenda commands. (line 161) * S- <2>: The date/time prompt. (line 36) @@ -6158,171 +6230,172 @@ Key Index  Tag Table: Node: Top964 -Node: Introduction10833 -Node: Summary11248 -Node: Installation14160 -Node: Activation15538 -Node: Feedback16787 -Node: Document structure18863 -Node: Outlines19637 -Node: Headlines20297 -Node: Visibility cycling20920 -Ref: Visibility cycling-Footnote-123011 -Ref: Visibility cycling-Footnote-223069 -Ref: Visibility cycling-Footnote-323119 -Node: Motion23388 -Node: Structure editing24172 -Node: Archiving26998 -Node: ARCHIVE tag27556 -Node: Moving subtrees29349 -Node: Sparse trees30390 -Ref: Sparse trees-Footnote-132521 -Ref: Sparse trees-Footnote-232703 -Node: Plain lists32818 -Ref: Plain lists-Footnote-136343 -Ref: Plain lists-Footnote-236700 -Node: Tables36884 -Node: Built-in table editor37432 -Node: Narrow columns45460 -Ref: Narrow columns-Footnote-147399 -Node: Table calculations47445 -Node: Formula syntax48765 -Ref: Formula syntax-Footnote-151670 -Node: Lisp formulas51970 -Node: Column formulas52759 -Node: Advanced features54521 -Node: Named-field formulas57775 -Node: Editing/debugging formulas58415 -Node: Appetizer60173 -Node: orgtbl-mode61276 -Node: table.el61767 -Node: Hyperlinks62744 -Node: Link format63517 -Node: Internal links64810 -Ref: Internal links-Footnote-166799 -Node: Radio targets66931 -Node: CamelCase links67646 -Node: External links68240 -Node: Handling links70644 -Ref: Handling links-Footnote-175296 -Ref: Handling links-Footnote-275533 -Node: Link abbreviations75607 -Node: Search options77286 -Ref: Search options-Footnote-179066 -Node: Custom searches79147 -Node: Remember80195 -Node: TODO items83889 -Node: TODO basics84871 -Node: TODO extensions86398 -Node: Workflow states87193 -Node: TODO types88178 -Ref: TODO types-Footnote-189836 -Node: Per file keywords89918 -Ref: Per file keywords-Footnote-191372 -Node: Priorities91573 -Node: Breaking down tasks92817 -Ref: Breaking down tasks-Footnote-193336 -Node: Checkboxes93432 -Node: Timestamps96187 -Node: Time stamps96648 -Ref: Time stamps-Footnote-1100142 -Ref: Time stamps-Footnote-2100258 -Node: Creating timestamps100413 -Node: The date/time prompt103039 -Ref: The date/time prompt-Footnote-1104805 -Node: Custom time format104911 -Node: Progress logging106470 -Node: Closing items107119 -Ref: Closing items-Footnote-1108053 -Ref: Closing items-Footnote-2108122 -Node: Tracking TODO state changes108195 -Node: Clocking work time109051 -Ref: Clocking work time-Footnote-1112697 -Ref: Clocking work time-Footnote-2112775 -Node: Tags112901 -Node: Tag inheritance113663 -Node: Setting tags114600 -Ref: Setting tags-Footnote-1118799 -Ref: Setting tags-Footnote-2118911 -Node: Tag searches118994 -Node: Agenda views121706 -Node: Agenda files123646 -Ref: Agenda files-Footnote-1124606 -Ref: Agenda files-Footnote-2124755 -Node: Agenda dispatcher124948 -Node: Built-in agenda views126639 -Node: Weekly/Daily agenda127217 -Node: Global TODO list129346 -Node: Matching headline tags131519 -Node: Timeline132590 -Node: Stuck projects133256 -Node: Presentation and sorting134955 -Node: Categories135746 -Node: Time-of-day specifications136410 -Node: Sorting of agenda items138381 -Node: Agenda commands139663 -Node: Custom agenda views146316 -Node: Storing searches146991 -Node: Block agenda148903 -Node: Setting Options150133 -Node: Batch processing152845 -Node: Embedded LaTeX153975 -Ref: Embedded LaTeX-Footnote-1155067 -Node: Math symbols155257 -Node: Subscripts and Superscripts156022 -Node: LaTeX fragments156866 -Ref: LaTeX fragments-Footnote-1158974 -Node: Processing LaTeX fragments159236 -Node: CDLaTeX mode160182 -Ref: CDLaTeX mode-Footnote-1162666 -Node: Exporting162814 -Node: ASCII export164128 -Node: HTML export165418 -Node: Export commands166037 -Node: Quoting HTML tags166761 -Node: Links167104 -Node: Images167801 -Ref: Images-Footnote-1168672 -Node: CSS support168733 -Ref: CSS support-Footnote-1170052 -Node: XOXO export170165 -Node: iCalendar export170604 -Node: Text interpretation172427 -Node: Comment lines172906 -Node: Enhancing text173377 -Node: Export options175069 -Node: Publishing176736 -Ref: Publishing-Footnote-1177532 -Node: Configuration177728 -Node: Project alist178446 -Node: Sources and destinations179512 -Node: Selecting files180242 -Node: Publishing action180990 -Node: Publishing options182223 -Node: Publishing links184375 -Node: Project page index185888 -Node: Sample configuration186666 -Node: Simple example187158 -Node: Complex example187831 -Node: Triggering publication189907 -Node: Miscellaneous190592 -Node: Completion191226 -Node: Customization192697 -Node: In-buffer settings193280 -Node: The very busy C-c C-c key197139 -Node: Clean view198783 -Node: TTY keys201360 -Node: Interaction202969 -Node: Cooperation203366 -Node: Conflicts205233 -Node: Bugs206825 -Node: Extensions and Hacking208219 -Node: Extensions208723 -Node: Dynamic blocks210510 -Node: Special agenda views212466 -Ref: Special agenda views-Footnote-1214747 -Node: History and Acknowledgments215007 -Node: Index220134 -Node: Key Index248617 +Node: Introduction10853 +Node: Summary11268 +Node: Installation14180 +Node: Activation15558 +Node: Feedback16807 +Node: Document structure18883 +Node: Outlines19657 +Node: Headlines20317 +Node: Visibility cycling20940 +Ref: Visibility cycling-Footnote-123031 +Ref: Visibility cycling-Footnote-223089 +Ref: Visibility cycling-Footnote-323139 +Node: Motion23408 +Node: Structure editing24192 +Node: Archiving27018 +Node: ARCHIVE tag27576 +Node: Moving subtrees29369 +Node: Sparse trees30680 +Ref: Sparse trees-Footnote-132811 +Ref: Sparse trees-Footnote-232993 +Node: Plain lists33108 +Ref: Plain lists-Footnote-136633 +Ref: Plain lists-Footnote-236990 +Node: Tables37174 +Node: Built-in table editor37722 +Node: Narrow columns45999 +Ref: Narrow columns-Footnote-147938 +Node: Table calculations47984 +Node: Formula syntax49304 +Ref: Formula syntax-Footnote-152209 +Node: Lisp formulas52509 +Node: Column formulas53298 +Node: Advanced features55060 +Node: Named-field formulas58314 +Node: Editing/debugging formulas58954 +Node: Appetizer60712 +Node: orgtbl-mode61815 +Node: table.el62306 +Node: Hyperlinks63283 +Node: Link format64056 +Node: Internal links65349 +Ref: Internal links-Footnote-167338 +Node: Radio targets67470 +Node: CamelCase links68185 +Node: External links68779 +Node: Handling links71183 +Ref: Handling links-Footnote-175835 +Ref: Handling links-Footnote-276072 +Node: Link abbreviations76146 +Node: Search options77825 +Ref: Search options-Footnote-179605 +Node: Custom searches79686 +Node: Remember80734 +Node: TODO items84428 +Node: TODO basics85410 +Node: TODO extensions86937 +Node: Workflow states87732 +Node: TODO types88717 +Ref: TODO types-Footnote-190375 +Node: Per file keywords90457 +Ref: Per file keywords-Footnote-191911 +Node: Priorities92112 +Node: Breaking down tasks93356 +Ref: Breaking down tasks-Footnote-193875 +Node: Checkboxes93971 +Node: Timestamps96726 +Node: Time stamps97260 +Ref: Time stamps-Footnote-1100754 +Ref: Time stamps-Footnote-2100870 +Node: Creating timestamps101025 +Node: The date/time prompt103651 +Ref: The date/time prompt-Footnote-1105417 +Node: Custom time format105523 +Node: Repeating items107081 +Node: Progress logging108892 +Node: Closing items109538 +Ref: Closing items-Footnote-1110472 +Ref: Closing items-Footnote-2110541 +Node: Tracking TODO state changes110614 +Node: Clocking work time111470 +Ref: Clocking work time-Footnote-1115116 +Ref: Clocking work time-Footnote-2115194 +Node: Tags115320 +Node: Tag inheritance116082 +Node: Setting tags117019 +Ref: Setting tags-Footnote-1121218 +Ref: Setting tags-Footnote-2121330 +Node: Tag searches121413 +Node: Agenda views124125 +Node: Agenda files126065 +Ref: Agenda files-Footnote-1127025 +Ref: Agenda files-Footnote-2127174 +Node: Agenda dispatcher127367 +Node: Built-in agenda views129058 +Node: Weekly/Daily agenda129636 +Node: Global TODO list131765 +Node: Matching headline tags133938 +Node: Timeline135009 +Node: Stuck projects135675 +Node: Presentation and sorting137374 +Node: Categories138165 +Node: Time-of-day specifications138829 +Node: Sorting of agenda items140800 +Node: Agenda commands142082 +Node: Custom agenda views148735 +Node: Storing searches149410 +Node: Block agenda151322 +Node: Setting Options152552 +Node: Batch processing155264 +Node: Embedded LaTeX156394 +Ref: Embedded LaTeX-Footnote-1157486 +Node: Math symbols157676 +Node: Subscripts and Superscripts158441 +Node: LaTeX fragments159285 +Ref: LaTeX fragments-Footnote-1161393 +Node: Processing LaTeX fragments161655 +Node: CDLaTeX mode162601 +Ref: CDLaTeX mode-Footnote-1165085 +Node: Exporting165233 +Node: ASCII export166547 +Node: HTML export167837 +Node: Export commands168456 +Node: Quoting HTML tags169180 +Node: Links169523 +Node: Images170220 +Ref: Images-Footnote-1171091 +Node: CSS support171152 +Ref: CSS support-Footnote-1172471 +Node: XOXO export172584 +Node: iCalendar export173023 +Node: Text interpretation174846 +Node: Comment lines175325 +Node: Enhancing text175796 +Node: Export options177488 +Node: Publishing179155 +Ref: Publishing-Footnote-1179951 +Node: Configuration180147 +Node: Project alist180865 +Node: Sources and destinations181931 +Node: Selecting files182661 +Node: Publishing action183409 +Node: Publishing options184642 +Node: Publishing links186794 +Node: Project page index188307 +Node: Sample configuration189085 +Node: Simple example189577 +Node: Complex example190250 +Node: Triggering publication192326 +Node: Miscellaneous193011 +Node: Completion193645 +Node: Customization195116 +Node: In-buffer settings195699 +Node: The very busy C-c C-c key199940 +Node: Clean view201584 +Node: TTY keys204161 +Node: Interaction205770 +Node: Cooperation206167 +Node: Conflicts208034 +Node: Bugs209626 +Node: Extensions and Hacking211020 +Node: Extensions211524 +Node: Dynamic blocks213467 +Node: Special agenda views215423 +Ref: Special agenda views-Footnote-1217704 +Node: History and Acknowledgments217964 +Node: Index223323 +Node: Key Index252098  End Tag Table diff --git a/org.el b/org.el index e8cf734cd..d97bab496 100644 --- a/org.el +++ b/org.el @@ -1,11 +1,11 @@ ;;;; org.el --- Outline-based notes management and organize ;; Carstens outline-mode for keeping track of everything. -;; Copyright (C) 2004, 2005, 2006 Free Software Foundation, Inc. +;; Copyright (C) 2004, 2005, 2006, 2007 Free Software Foundation, Inc. ;; ;; Author: Carsten Dominik ;; Keywords: outlines, hypermedia, calendar, wp ;; Homepage: http://www.astro.uva.nl/~dominik/Tools/org/ -;; Version: 4.60 +;; Version: 4.61 ;; ;; This file is part of GNU Emacs. ;; @@ -61,6 +61,17 @@ ;; ;; Recent changes ;; -------------- +;; Version 4.61 +;; - Avoiding keybinding clashes with flyspell +;; - Archiving is now also on `C-C C-x C-s' (was just `C-c $') +;; - Cycling through agenda files is now also on "C-'" (was just "C-,") +;; - Colon is considered part of number, to align times in clock tables. +;; - Fixed bug for list of stuck projects. +;; - Fixed several bugs/problems concerning linking to gnus. +;; - Block agendas can contain the list of stuck projects. +;; - #+ARCHIVE may now appear several times in the buffer. +;; - More bug fixes. +;; ;; Version 4.60 ;; - HTML export: inlining images, clickable images (manual 10.2.4). ;; - Incremental search now shows proper context when exiting. @@ -127,7 +138,7 @@ ;;; Version -(defvar org-version "4.60" +(defvar org-version "4.61" "The version number of the file org.el.") (defun org-version () (interactive) @@ -734,7 +745,7 @@ this variable requires a restart of Emacs to become effective." :type 'string) (defcustom org-table-number-regexp - "^\\([<>]?[-+^.0-9]*[0-9][-+^.0-9eEdDx()%]*\\|\\(0[xX]\\)[0-9a-fA-F]+\\)$" + "^\\([<>]?[-+^.0-9]*[0-9][-+^.0-9eEdDx()%:]*\\|\\(0[xX]\\)[0-9a-fA-F]+\\)$" "Regular expression for recognizing numbers in table columns. If a table column contains mostly numbers, it will be aligned to the right. If not, it will be aligned to the left. @@ -1677,6 +1688,7 @@ cmd An agenda command, similar to the above. However, tree commands So valid commands for a set are: (agenda) (alltodo) + (stuck) (todo \"match\" options) (tags \"match\" options ) (tags-todo \"match\" options) @@ -1707,6 +1719,7 @@ precedence over the general options." (choice (const :tag "Agenda" (agenda)) (const :tag "TODO list" (alltodo)) + (const :tag "Stuck projects" (stuck)) (list :tag "Tags search" (const :format "" tags) (string :tag "Match") @@ -3521,6 +3534,11 @@ The following commands are available: ;; Paragraphs and auto-filling (org-set-autofill-regexps) (org-update-radio-target-regexp) + + ;; Comment characters + (org-set-local 'comment-start "#") + (org-set-local 'comment-padding " ") + ;; Make isearch reveal context (if (or (featurep 'xemacs) (not (boundp 'outline-isearch-open-invisible-function))) @@ -4519,16 +4537,28 @@ in the region." (org-demote))) (org-fix-position-after-promote)) +;; FIXME: check and remove +;(defun org-fix-position-after-promote () +; "Make sure that after pro/demotion cursor position is right." +; (if (and (or (eobp) (equal (char-after) ?\n)) +; (save-excursion +; (skip-chars-backward "a-zA-Z0-9_@") +; (looking-at org-todo-regexp))) +; (insert " ")) +; (and (equal (char-after) ?\ ) +; (equal (char-before) ?*) +; (forward-char 1))) + (defun org-fix-position-after-promote () "Make sure that after pro/demotion cursor position is right." - (if (and (or (eobp) (equal (char-after) ?\n)) - (save-excursion - (skip-chars-backward "a-zA-Z0-9_@") - (looking-at org-todo-regexp))) - (insert " ")) - (and (equal (char-after) ?\ ) - (equal (char-before) ?*) - (forward-char 1))) + (let ((pos (point))) + (when (save-excursion + (beginning-of-line 1) + (looking-at org-todo-line-regexp) + (or (equal pos (match-end 1)) (equal pos (match-end 2)))) + (cond ((eobp) (insert " ")) + ((eolp) (insert " ")) + ((equal (char-after) ?\ ) (forward-char 1)))))) (defun org-get-legal-level (level &optional change) "Rectify a level change under the influence of `org-odd-levels-only' @@ -5440,7 +5470,15 @@ this heading. " (tr-org-todo-regexp org-todo-regexp) (tr-org-todo-line-regexp org-todo-line-regexp) (this-buffer (current-buffer)) + (org-archive-location org-archive-location) + (re "^#\\+ARCHIVE:[ \t]+\\(\\S-.*\\S-\\)[ \t]*$") file heading buffer level newfile-p) + + ;; Try to find a local archive location + (save-excursion + (if (or (re-search-backward re nil t) (re-search-forward re nil t)) + (setq org-archive-location (match-string 1)))) + (if (string-match "\\(.*\\)::\\(.*\\)" org-archive-location) (progn (setq file (format (match-string 1 org-archive-location) @@ -6239,6 +6277,13 @@ is always the old value." val) (forward-char 1) "")) +(defun org-table-field-info () + (interactive) + (let ((current (org-table-get-field)) + (col (org-table-current-column)) + (line (org-table-current-line))) + (message "Table data line %d, column %d" line col))) + (defun org-table-current-column () "Find out which column we are in. When called interactively, column is also displayed in echo area." @@ -6252,6 +6297,20 @@ When called interactively, column is also displayed in echo area." (if (interactive-p) (message "This is table column %d" cnt)) cnt))) +(defun org-table-current-line () + "Find out what table line we are in. +Only datalins count for this." + (interactive) + (if (interactive-p) (org-table-check-inside-data-field)) + (save-excursion + (let ((cnt 0) (pos (point))) + (goto-char (org-table-begin)) + (while (< (point) pos) + (if (looking-at org-table-dataline-regexp) (setq cnt (1+ cnt))) + (beginning-of-line 2)) + (if (interactive-p) (message "This is table line %d" cnt)) + cnt))) + (defun org-table-goto-column (n &optional on-delim force) "Move the cursor to the Nth column in the current table line. With optional argument ON-DELIM, stop with point before the left delimiter @@ -7071,8 +7130,22 @@ the current column, to avoid unnecessary parsing." (defvar org-table-named-field-locations nil "Alist with locations of named fields.") +(defun org-table-current-field-formula () + "Return the formula active for the current field. +Assumes that specials are in place." + (let* ((name (car (rassoc (list (org-current-line) + (org-table-current-column)) + org-table-named-field-locations))) + (scol (if name name + (int-to-string (org-table-current-column)))) + (stored-list (org-table-get-stored-formulas)) + (stored (cdr (assoc scol stored-list)))) + (if stored (concat (if name ":=" "=") stored)))) + (defun org-table-get-formula (&optional equation named) - "Read a formula from the minibuffer, offer stored formula as default." + "Read a formula from the minibuffer, offer stored formula as default. +When NAMED is non-nil, look for a named equation. +When JUST-RETURN is non-nil, return equation without prompting." (let* ((name (car (rassoc (list (org-current-line) (org-table-current-column)) org-table-named-field-locations))) @@ -7379,6 +7452,11 @@ formula, by storing it in a special line below the table. When called with a `C-u' prefix, the current field must ba a named field, and the formula is installed as valid in only this specific field. +When called with two `C-u' prefixes, insert the active equation +for the field back into the current field, so that it can be +edited there. This is useful in order to use \\[org-show-variable] to check +the referenced fields. + When called, the command first prompts for a formula, which is read in the minibuffer. Previously entered formulas are available through the history list, and the last used formula is offered as a default. @@ -7400,110 +7478,116 @@ not overwrite the stored one." (interactive "P") (org-table-check-inside-data-field) (org-table-get-specials) - (let* (fields - (ndown (if (integerp arg) arg 1)) - (org-table-automatic-realign nil) - (case-fold-search nil) - (down (> ndown 1)) - (formula (if (and equation suppress-store) - equation - (org-table-get-formula equation (equal arg '(4))))) - (n0 (org-table-current-column)) - (modes (copy-sequence org-calc-default-modes)) - n form fmt x ev orig c lispp) - ;; Parse the format string. Since we have a lot of modes, this is - ;; a lot of work. However, I think calc still uses most of the time. - (if (string-match ";" formula) - (let ((tmp (org-split-string formula ";"))) - (setq formula (car tmp) - fmt (concat (cdr (assoc "%" org-table-local-parameters)) - (nth 1 tmp))) - (while (string-match "\\([pnfse]\\)\\(-?[0-9]+\\)" fmt) - (setq c (string-to-char (match-string 1 fmt)) - n (string-to-number (match-string 2 fmt))) - (if (= c ?p) - (setq modes (org-set-calc-mode 'calc-internal-prec n)) - (setq modes (org-set-calc-mode - 'calc-float-format - (list (cdr (assoc c '((?n . float) (?f . fix) - (?s . sci) (?e . eng)))) - n)))) - (setq fmt (replace-match "" t t fmt))) - (while (string-match "[DRFS]" fmt) - (setq modes (org-set-calc-mode (match-string 0 fmt))) - (setq fmt (replace-match "" t t fmt))) - (unless (string-match "\\S-" fmt) - (setq fmt nil)))) - (if (and (not suppress-const) org-table-formula-use-constants) - (setq formula (org-table-formula-substitute-names formula))) - (setq orig (or (get-text-property 1 :orig-formula formula) "?")) - (while (> ndown 0) - (setq fields (org-split-string - (buffer-substring - (point-at-bol) (point-at-eol)) " *| *")) - (if org-table-formula-numbers-only - (setq fields (mapcar - (lambda (x) (number-to-string (string-to-number x))) - fields))) - (setq ndown (1- ndown)) - (setq form (copy-sequence formula) - lispp (equal (substring form 0 2) "'(")) - ;; Insert the references to fields in same row - (while (string-match "\\$\\([0-9]+\\)?" form) - (setq n (if (match-beginning 1) - (string-to-number (match-string 1 form)) - n0) - x (nth (1- n) fields)) - (unless x (error "Invalid field specifier \"%s\"" - (match-string 0 form))) - (if (equal x "") (setq x "0")) - (setq form (replace-match - (if lispp x (concat "(" x ")")) - t t form))) - ;; Insert ranges in current column - (while (string-match "\\&[-I0-9]+" form) - (setq form (replace-match - (save-match-data - (org-table-get-vertical-vector (match-string 0 form) - nil n0)) - t t form))) - (if lispp - (setq ev (eval (eval (read form))) - ev (if (numberp ev) (number-to-string ev) ev)) - (or (fboundp 'calc-eval) - (error "Calc does not seem to be installed, and is needed to evaluate the formula")) - (setq ev (calc-eval (cons form modes) - (if org-table-formula-numbers-only 'num)))) - - (when org-table-formula-debug - (with-output-to-temp-buffer "*Help*" - (princ (format "Substitution history of formula + (if (equal arg '(16)) + (let ((eq (org-table-current-field-formula))) + (or eq (error "No equation active for current field")) + (org-table-get-field nil eq) + (org-table-align) + (setq org-table-may-need-update t)) + (let* (fields + (ndown (if (integerp arg) arg 1)) + (org-table-automatic-realign nil) + (case-fold-search nil) + (down (> ndown 1)) + (formula (if (and equation suppress-store) + equation + (org-table-get-formula equation (equal arg '(4))))) + (n0 (org-table-current-column)) + (modes (copy-sequence org-calc-default-modes)) + n form fmt x ev orig c lispp) + ;; Parse the format string. Since we have a lot of modes, this is + ;; a lot of work. However, I think calc still uses most of the time. + (if (string-match ";" formula) + (let ((tmp (org-split-string formula ";"))) + (setq formula (car tmp) + fmt (concat (cdr (assoc "%" org-table-local-parameters)) + (nth 1 tmp))) + (while (string-match "\\([pnfse]\\)\\(-?[0-9]+\\)" fmt) + (setq c (string-to-char (match-string 1 fmt)) + n (string-to-number (match-string 2 fmt))) + (if (= c ?p) + (setq modes (org-set-calc-mode 'calc-internal-prec n)) + (setq modes (org-set-calc-mode + 'calc-float-format + (list (cdr (assoc c '((?n . float) (?f . fix) + (?s . sci) (?e . eng)))) + n)))) + (setq fmt (replace-match "" t t fmt))) + (while (string-match "[DRFS]" fmt) + (setq modes (org-set-calc-mode (match-string 0 fmt))) + (setq fmt (replace-match "" t t fmt))) + (unless (string-match "\\S-" fmt) + (setq fmt nil)))) + (if (and (not suppress-const) org-table-formula-use-constants) + (setq formula (org-table-formula-substitute-names formula))) + (setq orig (or (get-text-property 1 :orig-formula formula) "?")) + (while (> ndown 0) + (setq fields (org-split-string + (buffer-substring + (point-at-bol) (point-at-eol)) " *| *")) + (if org-table-formula-numbers-only + (setq fields (mapcar + (lambda (x) (number-to-string (string-to-number x))) + fields))) + (setq ndown (1- ndown)) + (setq form (copy-sequence formula) + lispp (and (> (length form) 2)(equal (substring form 0 2) "'("))) + ;; Insert the references to fields in same row + (while (string-match "\\$\\([0-9]+\\)?" form) + (setq n (if (match-beginning 1) + (string-to-number (match-string 1 form)) + n0) + x (nth (1- n) fields)) + (unless x (error "Invalid field specifier \"%s\"" + (match-string 0 form))) + (if (equal x "") (setq x "0")) + (setq form (replace-match + (if lispp x (concat "(" x ")")) + t t form))) + ;; Insert ranges in current column + (while (string-match "\\&[-I0-9]+" form) + (setq form (replace-match + (save-match-data + (org-table-get-vertical-vector (match-string 0 form) + nil n0)) + t t form))) + (if lispp + (setq ev (eval (eval (read form))) + ev (if (numberp ev) (number-to-string ev) ev)) + (or (fboundp 'calc-eval) + (error "Calc does not seem to be installed, and is needed to evaluate the formula")) + (setq ev (calc-eval (cons form modes) + (if org-table-formula-numbers-only 'num)))) + + (when org-table-formula-debug + (with-output-to-temp-buffer "*Help*" + (princ (format "Substitution history of formula Orig: %s $xyz-> %s $1-> %s\n" orig formula form)) - (if (listp ev) - (princ (format " %s^\nError: %s" - (make-string (car ev) ?\-) (nth 1 ev))) - (princ (format "Result: %s\nFormat: %s\nFinal: %s" - ev (or fmt "NONE") - (if fmt (format fmt (string-to-number ev)) ev))))) - (shrink-window-if-larger-than-buffer (get-buffer-window "*Help*")) - (unless (and (interactive-p) (not ndown)) - (unless (let (inhibit-redisplay) - (y-or-n-p "Debugging Formula. Continue to next? ")) - (org-table-align) - (error "Abort")) - (delete-window (get-buffer-window "*Help*")) - (message ""))) - (if (listp ev) (setq fmt nil ev "#ERROR")) - (org-table-justify-field-maybe - (if fmt (format fmt (string-to-number ev)) ev)) - (if (and down (> ndown 0) (looking-at ".*\n[ \t]*|[^-]")) - (call-interactively 'org-return) - (setq ndown 0))) - (and down (org-table-maybe-recalculate-line)) - (or suppress-align (and org-table-may-need-update - (org-table-align))))) + (if (listp ev) + (princ (format " %s^\nError: %s" + (make-string (car ev) ?\-) (nth 1 ev))) + (princ (format "Result: %s\nFormat: %s\nFinal: %s" + ev (or fmt "NONE") + (if fmt (format fmt (string-to-number ev)) ev))))) + (shrink-window-if-larger-than-buffer (get-buffer-window "*Help*")) + (unless (and (interactive-p) (not ndown)) + (unless (let (inhibit-redisplay) + (y-or-n-p "Debugging Formula. Continue to next? ")) + (org-table-align) + (error "Abort")) + (delete-window (get-buffer-window "*Help*")) + (message ""))) + (if (listp ev) (setq fmt nil ev "#ERROR")) + (org-table-justify-field-maybe + (if fmt (format fmt (string-to-number ev)) ev)) + (if (and down (> ndown 0) (looking-at ".*\n[ \t]*|[^-]")) + (call-interactively 'org-return) + (setq ndown 0))) + (and down (org-table-maybe-recalculate-line)) + (or suppress-align (and org-table-may-need-update + (org-table-align)))))) (defun org-table-recalculate (&optional all noalign) "Recalculate the current table line by applying all stored formulas. @@ -7627,8 +7711,7 @@ Parameters get priority." (defun org-table-edit-formulas () "Edit the formulas of the current table in a separate buffer." (interactive) - (unless (org-at-table-p) - (error "Not at a table")) + (unless (org-at-table-p) (error "Not at a table")) (org-table-get-specials) (let ((eql (org-table-get-stored-formulas)) (pos (move-marker (make-marker) (point))) @@ -7658,6 +7741,7 @@ Parameters get priority." (goto-char (point-min)) (message "Edit formulas and finish with `C-c C-c'."))) +;; FIXME: make this work in fields, directly highlighting the referenced fields (defun org-show-variable () "Show the location/value of the $ expression at point." (interactive) @@ -7896,7 +7980,7 @@ to execute outside of tables." (list (org-key 'S-return) 'org-table-copy-down) '([(meta return)] org-table-wrap-region) '("\C-c\C-q" org-table-wrap-region) - '("\C-c?" org-table-current-column) + '("\C-c?" org-table-field-info) '("\C-c " org-table-blank-field) '("\C-c+" org-table-sum) '("\C-c=" org-table-eval-formula) @@ -8157,6 +8241,7 @@ For file links, arg negates `org-context-in-file-links'." ((fboundp 'gnus-group-name) (gnus-group-name)) (t "???")))) + (unless group (error "Not on a group")) (setq cpltxt (concat (if (org-xor arg org-usenet-links-prefer-google) "http://groups.google.com/groups?group=" @@ -8165,11 +8250,9 @@ For file links, arg negates `org-context-in-file-links'." link (org-make-link cpltxt)))) ((memq major-mode '(gnus-summary-mode gnus-article-mode)) - (require 'gnus-sum) ; FIXME: I don't think this is needed, actually (and (eq major-mode 'gnus-article-mode) (gnus-article-show-summary)) - (gnus-summary-beginning-of-article) - (let* ((group (car gnus-article-current)) - (article (cdr gnus-article-current)) + (let* ((group gnus-newsgroup-name) + (article (gnus-summary-article-number)) (header (gnus-summary-article-header article)) (author (mail-header-from header)) (message-id (mail-header-id header)) @@ -9046,14 +9129,10 @@ onto the ring." (require 'gnus) (funcall (cdr (assq 'gnus org-link-frame-setup))) (if gnus-other-frame-object (select-frame gnus-other-frame-object)) - (if group (gnus-fetch-group group)) - (if article - (or (gnus-summary-goto-article article nil 'force) - (if (fboundp 'gnus-summary-insert-cached-articles) - (progn - (gnus-summary-insert-cached-articles) - (gnus-summary-goto-article article nil 'force)) - (message "Message could not be found."))))) + (cond ((and group article) + (gnus-group-read-group t nil group (list (string-to-number article))) + (gnus-summary-select-article)) + (group (gnus-group-jump-to-group group)))) (defun org-follow-vm-link (&optional folder article readonly) "Follow a VM link to FOLDER and ARTICLE." @@ -9902,7 +9981,7 @@ For calling through lisp, arg is also interpreted in the following way: ;; Fixup tag positioning (and org-auto-align-tags (org-set-tags nil t)) (run-hooks 'org-after-todo-state-change-hook) - ;; (and (equal state org-done-string) (org-auto-repeat-maybe)) + (and (equal state org-done-string) (org-auto-repeat-maybe)) )) ;; Fixup cursor location if close to the keyword (if (and (outline-on-heading-p) @@ -9914,7 +9993,6 @@ For calling through lisp, arg is also interpreted in the following way: (goto-char (or (match-end 2) (match-end 1))) (just-one-space)))) - (defun org-get-repeat () "Return the REPEAT statement of this entry." (save-match-data @@ -10011,9 +10089,7 @@ be removed." ((eq what 'closed) org-closed-string)) " ") (org-insert-time-stamp time nil (eq what 'closed)) - (end-of-line 1) -;;FIXME (and (eq what 'closed) (org-add-log-maybe 'done)) - ) + (end-of-line 1)) (goto-char (point-min)) (widen) (if (looking-at "[ \t]+\r?\n") @@ -10025,6 +10101,9 @@ be removed." (defvar org-log-note-state nil) (defvar org-log-note-window-configuration nil) (defvar org-log-note-return-to (make-marker)) +(defvar org-log-post-message nil + "Message to be displayed after a log note has been stored. +The auto-repeater uses this.") (defun org-add-log-maybe (&optional purpose state findpos) (save-excursion @@ -10051,7 +10130,7 @@ be removed." (goto-char org-log-note-marker) (switch-to-buffer-other-window "*Org Note*") (erase-buffer) - (org-mode) + (let ((org-inhibit-startup t)) (org-mode)) (insert (format "# Insert note for %s, finish with C-c C-c.\n\n" (cond ((eq org-log-note-purpose 'clock-out) "stopped clock") @@ -10089,6 +10168,7 @@ be removed." (set-buffer (marker-buffer org-log-note-marker)) (save-excursion (goto-char org-log-note-marker) + (move-marker org-log-note-marker nil) (end-of-line 1) (if (not (bolp)) (insert "\n")) (indent-relative nil) (setq ind (concat (buffer-substring (point-at-bol) (point)) " ")) @@ -10097,7 +10177,9 @@ be removed." (insert "\n" ind (pop lines)))))) (set-window-configuration org-log-note-window-configuration) (with-current-buffer (marker-buffer org-log-note-return-to) - (goto-char org-log-note-return-to))) + (goto-char org-log-note-return-to)) + (move-marker org-log-note-return-to nil) + (and org-log-post-message (message org-log-post-message))) (defvar org-occur-highlights nil) (make-variable-buffer-local 'org-occur-highlights) @@ -10303,7 +10385,6 @@ are included in the output." (when (eq action 'sparse-tree) (org-overview)) (while (re-search-forward re nil t) (catch :skip - (and (eq action 'agenda) (org-agenda-skip)) (setq todo (if (match-end 1) (match-string 2)) tags (if (match-end 4) (match-string 4))) (goto-char (setq lspos (1+ (match-beginning 0)))) @@ -10329,6 +10410,7 @@ are included in the output." (eval matcher) (or (not org-agenda-skip-archived-trees) (not (member org-archive-tag tags-list)))) + (and (eq action 'agenda) (org-agenda-skip)) ;; list this headline (if (eq action 'sparse-tree) (progn @@ -12110,9 +12192,9 @@ L Timeline for current buffer # List stuck projects (!=configure) '(face bold)) (cond ((stringp type) type) - ((eq type 'tags) "Tags query") ((eq type 'todo) "TODO keyword") - ((eq type 'tags-tree) "Tags (TODO)") + ((eq type 'tags) "Tags query") + ((eq type 'tags-todo) "Tags (TODO)") ((eq type 'tags-tree) "Tags tree") ((eq type 'todo-tree) "TODO kwd tree") ((eq type 'occur-tree) "Occur tree") @@ -12120,11 +12202,10 @@ L Timeline for current buffer # List stuck projects (!=configure) (t "???")) (if (stringp match) (org-add-props match nil 'face 'org-warning) - (format "set of %d commands" (+ -2 (length entry))))))) + (format "set of %d commands" (length match)))))) (if restrict-ok (insert "\n" (org-add-props "1 Restrict call to current buffer 0 Restrict call to region or subtree" nil 'face 'org-table))) - (goto-char (point-min)) (if (fboundp 'fit-window-to-buffer) (fit-window-to-buffer)) (message "Press key for agenda command%s" @@ -12217,6 +12298,8 @@ L Timeline for current buffer # List stuck projects (!=configure) (call-interactively 'org-agenda-list)) ((eq type 'alltodo) (call-interactively 'org-todo-list)) + ((eq type 'stuck) + (call-interactively 'org-agenda-list-stuck-projects)) ((eq type 'tags) (org-let2 gprops lprops '(org-tags-view current-prefix-arg match))) @@ -12490,7 +12573,9 @@ to all future agenda commands. Instead, bind it with `let' to scope it dynamically into the agenda-constructing command.") (defun org-agenda-skip () - "Throw to `:skip' in places that should be skipped." + "Throw to `:skip' in places that should be skipped. +Also moves point to the end of the skipped region, so that search can +continue from there." (let ((p (point-at-bol)) to) (and org-agenda-skip-archived-trees (get-text-property p :org-archived) @@ -13035,8 +13120,11 @@ MATCH is being ignored." (todo todo-re) (tags tags-re) (t (error "No information how to identify unstuck projects")))) - (org-tags-view nil matcher))) - + (org-tags-view nil matcher) + (with-current-buffer org-agenda-buffer-name + (setq org-agenda-redo-command + '(org-agenda-list-stuck-projects + (or current-prefix-arg org-last-arg)))))) ;;; Diary integration @@ -14072,6 +14160,13 @@ With prefix ARG, go back that many times `org-agenda-ndays'." "Detach overlay INDEX." (funcall (if (featurep 'xemacs) 'detach-extent 'delete-overlay) org-hl)) +(defun org-highlight-until-next-command (beg end &optional buffer) + (org-highlight beg end buffer) + (add-hook 'pre-command-hook 'org-unhighlight-once)) + +(defun org-unhighlight-once () + (remove-hook 'pre-command-hook 'org-unhighlight-once) + (org-unhighlight)) (defun org-agenda-follow-mode () "Toggle follow mode in an agenda buffer." @@ -14462,20 +14557,22 @@ the tags of the current headline come last." (interactive) (let (tags) (save-excursion - (goto-char (or pos (point))) - (save-match-data - (org-back-to-heading t) - (condition-case nil - (while t - (if (looking-at "[^\r\n]+?:\\([a-zA-Z_@0-9:]+\\):[ \t]*\\([\n\r]\\|\\'\\)") - (setq tags (append (org-split-string - (org-match-string-no-properties 1) ":") - tags))) + (save-restriction + (widen) + (goto-char (or pos (point))) + (save-match-data + (org-back-to-heading t) + (condition-case nil + (while t + (if (looking-at "[^\r\n]+?:\\([a-zA-Z_@0-9:]+\\):[ \t]*\\([\n\r]\\|\\'\\)") + (setq tags (append (org-split-string + (org-match-string-no-properties 1) ":") + tags))) (or org-use-tag-inheritance (error "")) (org-up-heading-all 1)) - (error nil)))) - tags)) - + (error nil)))) + tags))) + ;; FIXME: should fix the tags property of the agenda line. (defun org-agenda-set-tags () "Set tags for the current headline." @@ -15004,15 +15101,14 @@ The images can be removed again with \\[org-ctrl-c-ctrl-c]." (opt org-format-latex-options) (matchers (plist-get opt :matchers)) (re-list org-latex-regexps) - (cnt 0) txt link beg end re e oldfiles + (cnt 0) txt link beg end re e checkdir m n block linkfile movefile ov) - ;; Make sure the directory exists - (or (file-directory-p todir) (make-directory todir)) ;; Check if there are old images files with this prefix, and remove them - (setq oldfiles (directory-files - todir 'full - (concat (regexp-quote prefixnodir) "_[0-9]+\\.png$"))) - (while oldfiles (delete-file (pop oldfiles))) + (when (file-directory-p todir) + (mapc 'delete-file + (directory-files + todir 'full + (concat (regexp-quote prefixnodir) "_[0-9]+\\.png$")))) ;; Check the different regular expressions (while (setq e (pop re-list)) (setq m (car e) re (nth 1 e) n (nth 2 e) @@ -15029,6 +15125,9 @@ The images can be removed again with \\[org-ctrl-c-ctrl-c]." link (concat block "[[file:" linkfile "]]" block)) (if msg (message msg cnt)) (goto-char beg) + (unless checkdir ; make sure the directory exists + (setq checkdir t) + (or (file-directory-p todir) (make-directory todir))) (org-create-formula-image txt movefile opt) (if overlays @@ -17090,7 +17189,7 @@ file and store it under the name `org-combined-agenda-icalendar-file'." (and (not started) (setq started t) (org-start-icalendar-file org-icalendar-combined-name)) (org-start-icalendar-file category)) - (org-print-icalendar-entries combine category) + (org-print-icalendar-entries combine) (when (or (and combine (not files)) (not combine)) (org-finish-icalendar-file) (set-buffer ical-buffer) @@ -17104,23 +17203,23 @@ The iCalendar buffer is still current when this hook is run. A good way to use this is to tell a desktop calenndar application to re-read the iCalendar file.") - -;; FIXME: Strip down the links -(defun org-print-icalendar-entries (&optional combine category) +(defun org-print-icalendar-entries (&optional combine) "Print iCalendar entries for the current Org-mode file to `standard-output'. When COMBINE is non nil, add the category to each line." (let ((re2 (concat "--?-?\\(" org-ts-regexp "\\)")) + (org-category-table (org-get-category-table)) (dts (org-ical-ts-to-string (format-time-string (cdr org-time-stamp-formats) (current-time)) "DTSTART")) - hd ts ts2 state (inc t) pos scheduledp deadlinep tmp pri) + hd ts ts2 state (inc t) pos scheduledp deadlinep tmp pri category) (save-excursion (goto-char (point-min)) (while (re-search-forward org-ts-regexp nil t) (setq pos (match-beginning 0) ts (match-string 0) inc t - hd (org-get-heading)) + hd (org-get-heading) + category (org-get-category)) (if (looking-at re2) (progn (goto-char (match-end 0)) @@ -17312,6 +17411,7 @@ The XOXO buffer is named *xoxo-*" (define-key org-mode-map [(tab)] 'org-cycle) (define-key org-mode-map [(control tab)] 'org-force-cycle-archived) (define-key org-mode-map [(meta tab)] 'org-complete) +(define-key org-mode-map "\M-\t" 'org-complete) (define-key org-mode-map "\M-\C-i" 'org-complete) ;; The following line is necessary under Suse GNU/Linux (unless (featurep 'xemacs) @@ -17370,8 +17470,9 @@ The XOXO buffer is named *xoxo-*" (define-key org-mode-map "\C-c\C-a" 'show-all) ; in case allout messed up. (define-key org-mode-map "\C-c\C-r" 'org-reveal) (define-key org-mode-map "\C-xns" 'org-narrow-to-subtree) -(define-key org-mode-map "\C-c$" 'org-archive-subtree) +(define-key org-mode-map "\C-c\C-x\C-s" 'org-archive-subtree) (define-key org-mode-map "\C-c\C-x\C-a" 'org-toggle-archive-tag) +(define-key org-mode-map "\C-c$" 'org-archive-subtree) (define-key org-mode-map "\C-c\C-xb" 'org-tree-to-indirect-buffer) (define-key org-mode-map "\C-c\C-j" 'org-goto) (define-key org-mode-map "\C-c\C-t" 'org-todo) @@ -17396,6 +17497,7 @@ The XOXO buffer is named *xoxo-*" (define-key org-mode-map "\C-c>" 'org-goto-calendar) (define-key org-mode-map "\C-c<" 'org-date-from-calendar) (define-key org-mode-map [(control ?,)] 'org-cycle-agenda-files) +(define-key org-mode-map [(control ?\')] 'org-cycle-agenda-files) (define-key org-mode-map "\C-c[" 'org-agenda-file-to-front) (define-key org-mode-map "\C-c]" 'org-remove-file) (define-key org-mode-map "\C-c-" 'org-table-insert-hline) @@ -17403,7 +17505,7 @@ The XOXO buffer is named *xoxo-*" (define-key org-mode-map "\C-c\C-c" 'org-ctrl-c-ctrl-c) (define-key org-mode-map "\C-c#" 'org-update-checkbox-count) (define-key org-mode-map "\C-m" 'org-return) -(define-key org-mode-map "\C-c?" 'org-table-current-column) +(define-key org-mode-map "\C-c?" 'org-table-field-info) (define-key org-mode-map "\C-c " 'org-table-blank-field) (define-key org-mode-map "\C-c+" 'org-table-sum) (define-key org-mode-map "\C-c=" 'org-table-eval-formula) @@ -18519,6 +18621,14 @@ Show the heading too, if it is currently invisible." ;;;; Experimental code +(defcustom org-allow-auto-repeat t + "Non-nil means, find REPEAT cookies in entries and apply them. +A repeat cookie looks like REPEAT(+1m) and causes deadlines and schedules +to repeat themselves shifted by a certain amount of time, each time an +entry is marked DONE." + :group 'org??? + :type 'boolean) + (defun org-auto-repeat-maybe () "Check if the current headline contains a REPEAT key. If yes, set TODO state back to what it was and change any SCHEDULED @@ -18534,6 +18644,10 @@ This function should be run in the `org-after-todo-state-change-hook'." (org-todo (if (eq 'org-todo-interpretation 'type) last-state (car org-todo-keywords))) + (unless (memq 'org-add-log-note (default-value 'post-command-hook)) + ;; Make sure a note is taken + (let ((org-log-done '(done))) + (org-add-log-maybe 'done org-done-string 'findpos))) (org-back-to-heading t) (org-add-planning-info nil nil 'closed) (setq re (concat "\\(" org-scheduled-time-regexp "\\)\\|\\(" @@ -18549,7 +18663,8 @@ This function should be run in the `org-after-todo-state-change-hook'." (if (equal what "w") (setq n (* n 7) what "d")) (org-timestamp-change n (cdr (assoc what whata)))) (setq msg (concat msg type org-last-changed-timestamp " "))) - (message msg) (sit-for 1)))) + (setq org-log-post-message msg) + (message msg)))) ;;;; Finish up @@ -18559,3 +18674,4 @@ This function should be run in the `org-after-todo-state-change-hook'." ;; arch-tag: e77da1a7-acc7-4336-b19e-efa25af3f9fd ;;; org.el ends here + \ No newline at end of file diff --git a/org.pdf b/org.pdf index 810db3a03..cae5aaf42 100644 Binary files a/org.pdf and b/org.pdf differ diff --git a/org.texi b/org.texi index 26e0de111..017be403a 100644 --- a/org.texi +++ b/org.texi @@ -3,8 +3,8 @@ @setfilename ../info/org @settitle Org Mode Manual -@set VERSION 4.60 -@set DATE December 2006 +@set VERSION 4.61 +@set DATE January 2007 @dircategory Emacs @direntry @@ -171,6 +171,7 @@ Timestamps * Time stamps:: Assigning a time to a tree entry * Creating timestamps:: Commands which insert timestamps * Custom time format:: If you cannot work with the ISO format +* Repeating items:: * Progress logging:: Documenting when what work was done. Creating timestamps @@ -845,12 +846,12 @@ different location, either in the current file, or even in a different file, the archive file. @table @kbd -@kindex C-c $ -@item C-c $ +@kindex C-c C-x C-s +@item C-c C-x C-s 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 $ +@kindex C-u C-c C-x C-s +@item C-u C-c C-x C-s 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 @@ -863,7 +864,17 @@ 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}. +@code{org-archive-location}. There is also an in-buffer option for +setting this variable, for example + +@example +#+ARCHIVE: %s_done:: +@end example + +@noindent +You may have several such lines in the buffer, they will then be valid +for the entries following the line (the first will also apply to any +text before it). @node Sparse trees, Plain lists, Archiving, Document structure @section Sparse trees @@ -1214,7 +1225,8 @@ result. @kindex C-c ' @item C-c ' Edit all formulas associated with the current table in a separate -buffer. +buffer. Use @kbd{C-u C-u C-c =} to edit the formula directly in the +current field, to allow checking complex references with @kbd{C-c ?}. @kindex C-c * @item C-c * @@ -1232,8 +1244,9 @@ region, change all marks in the region. @kindex C-c ? @item C-c ? -Which table column is the cursor in? Displays number >0 in echo -area. +Display line and column number of current field in echo area. If the +cursor is currently editing a formula, the field or range referenced by +the expression at point will be highlighted. @cindex region, active @cindex active region @@ -2540,6 +2553,7 @@ planning. * Time stamps:: Assigning a time to a tree entry * Creating timestamps:: Commands which insert timestamps * Custom time format:: If you cannot work with the ISO format +* Repeating items:: Deadlines that come back again and again * Progress logging:: Documenting when what work was done. @end menu @@ -2802,7 +2816,7 @@ One month back. Choose date in calendar (only if nothing was typed into minibuffer). @end table -@node Custom time format, Progress logging, Creating timestamps, Timestamps +@node Custom time format, Repeating items, Creating timestamps, Timestamps @section Custom time format @cindex custom date/time format @cindex time format, custom @@ -2845,7 +2859,48 @@ using dates in tables, table alignment will be messed up. If the custom format is shorter, things do work as expected. @end itemize -@node Progress logging, , Custom time format, Timestamps +@node Repeating items, Progress logging, Custom time format, Timestamps +@section Repeating items +@cindex TODO items, repeating +@cindex Deadlines, repeating +@cindex Scheduling, repeating + +Org-mode integrates with the Emacs calendar and diary to display cyclic +appointments, anniversaries and other special entries in the agenda +(@pxref{Weekly/Daily agenda}). However, it can be useful to have +certain deadlines and scheduling items to auto-repeat. The advantage of +a deadline or scheduled item is that the they produce warnings ahead of +time and automatically forward themselves in the agenda until they are +done. The abstract difference is therefore between cyclic +@i{appointments} and cyclic @i{action items}. For appointments you +should use the diary, for actions you can uses an org-mode deadline or +scheduling time stamp together with a REPEAT cookie. For example: + +@example +* TODO Replace batteries in smoke detector REPEAT(+18m) + SCHEDULED: <2007-01-01 Mon> + +* TODO Get dentist appointment REPEAT(+6m) + SCHEDULED: <2006-12-19 Tue> + +* TODO Tax report to IRS REPEAT(+1y) + DEADLINE: <2007-04-01 Sun> +@end example + +Each time you try to mark one of these entries DONE using @kbd{C-c C-t}, +they will automatically switch back to the state TODO, and the +deadline/scheduling will be shifted accordingly. The time units +recognized by org-mode are year (y), month (m), week (w), and day (d). +Org-mode will also prompt you for a note and record the fact that you +have closed this item in a note under the headline. + +One unusual property of these repeating items is that only one instance +of each exist at any given time. So if you look back or ahead in the +agenda, you will not find past and future instances, only the current +one will show up. Use a cyclic diary entry if you need all past and +future instances to be visible in the angenda. + +@node Progress logging, , Repeating items, Timestamps @section Progress Logging @cindex progress logging @cindex logging, of progress @@ -3004,29 +3059,6 @@ The @kbd{l} key may be used in the timeline (@pxref{Timeline}) and in the agenda (@pxref{Weekly/Daily agenda}) to show which tasks have been worked on or closed during a day. -@c @node Self-repeating deadlines -@c @section Self-repeating deadlines -@c -@c Org-mode integrates with the Emacs calendar and diary to display cyclic -@c appointments and anniversaries in the agenda (@pxref{The weekly/daily -@c agenda}). However, it can be useful to have certain deadlines and -@c scheduling items to auto-repeat. The advantage of a deadline or -@c scheduled item is that the they produce warnings ahead of time and -@c automatically forward themselves in the agenda until they are done. The -@c abstract difference is therefore between cyclic @i{appointments} and -@c cyclic @i{action items}. For appointments you should use the diary, for -@c actions you can uses an org-mode deadline or scheduling time stamp -@c together with a REPEAT cookie. For example: -@c -@c @example -@c * TODO Income tax to IRS REPEAT(+1y) -@c DEADLINE: <2006-12-19 Tue> -@c @end example -@c -@c Each time you try to mark this entry DONE using @kbd{C-c C-t}, it will -@c automatically switch back to the state TODO, and the deadline will be -@c shifted by 1 year. - @node Tags, Agenda views, Timestamps, Top @chapter Tags @cindex tags @@ -5352,7 +5384,12 @@ These lines (several are allowed) specify link abbreviations. @item #+CATEGORY: This line sets the category for the agenda file. The category applies for all subsequent lines until the next @samp{#+CATEGORY} line, or the -end of the file. +end of the file. The first such line also applies to any entries before it. +@item #+ARCHIVE: %s_done:: +This line sets the archive location for the agenda file. It applies for +all subsequent lines until the next @samp{#+CATEGORY} line, or the end +of the file. The first such line also applies to any entries before it. +The correspoinding variable is @code{org-archive-location}. @item #+TBLFM: This line contains the formulas for the table directly above the line. @item #+TITLE:, #+AUTHOR:, #+EMAIL:, #+LANGUAGE:, #+TEXT:, #+OPTIONS: @@ -5715,9 +5752,13 @@ caused by the preparations for the 22.1 release. In the mean time, A blogging plug-in for @file{org-publish.el}.@* @url{http://dto.freeshell.org/notebook/OrgMode.html}. @cindex @file{blorg.el} -@item @file{blorg.el} by Bastien Guerry +@item @file{blorg.el} by Bastien Guerry Publish Org-mode files as blogs. @url{http://www.cognition.ens.fr/~guerry/blorg.html}. +@cindex @file{org2rem.el} +@item @file{org2rem.el} by Bastien Guerry +Translates Org-mode files into something readable by +Remind. @url{http://www.cognition.ens.fr/~guerry/u/org2rem.el}. @end table @node Dynamic blocks, Special agenda views, Extensions, Extensions and Hacking @@ -5853,11 +5894,11 @@ 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 +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. @itemize @bullet @@ -5894,10 +5935,13 @@ around a match in a hidden outline tree. @item @i{Niels Giessen} had the idea to automatically archive DONE trees. @item -@i{Bastien Guerry} provided extensive feedback. +@i{Bastien Guerry} provided extensive feedback and some patches, and +translated David O'Toole's tutorial into French. @item @i{Kai Grossjohann} pointed out key-binding conflicts with other packages. @item +@i{Shidai Liu} (``Leo'') provided extensive feedback and some patches. +@item @i{Leon Liu} asked for embedded LaTeX and tested it. @item @i{Stefan Monnier} provided a patch to keep the Emacs-Lisp compiler @@ -5908,6 +5952,9 @@ happy. @i{Tim O'Callaghan} suggested in-file links, search options for general file links, and TAGS. @item +@i{Takeshi Okano} translated the manual and David O'Toole's tutorial +into Japanese. +@item @i{Oliver Oppitz} suggested multi-state TODO items. @item @i{Scott Otterson} sparked the introduction of descriptive text for diff --git a/orgcard.pdf b/orgcard.pdf index e1820f407..715f71b3f 100644 Binary files a/orgcard.pdf and b/orgcard.pdf differ diff --git a/orgcard.tex b/orgcard.tex index 3226542c7..9d858e95e 100644 --- a/orgcard.tex +++ b/orgcard.tex @@ -1,5 +1,5 @@ % Reference Card for Org Mode -\def\orgversionnumber{4.60} +\def\orgversionnumber{4.61} \def\year{2006} % %**start of header @@ -317,8 +317,8 @@ are preserved on all copies. \key{toggle ARCHIVE tag}{C-c C-x C-a} \metax{mark fully done children}{C-u C-c C-x C-a} \key{force cycling of an ARCHIVEd tree}{C-TAB} -\key{move subtree to archive file}{C-c \$} -\key{move all fully done children}{C-u C-c \$} +\key{move subtree to archive file}{C-c C-x C-s} +\key{move all fully done children}{C-u C-c C-x C-s} To set archive location for current file, add a line like$^2$: \vskip -1mm \beginexample% @@ -391,7 +391,7 @@ Outside of tables, the same keys may have other functionality. \key{rotate calculation mark through \# * ! \^ \_ \$}{C-\#} -\key{display column number cursor is in}{C-c ?} +\key{show line, column, formula reference}{C-c ?} \key{sum numbers in current column/rectangle}{C-c +} \key{copy down with increment}{S-RET$^3$} @@ -566,7 +566,7 @@ after ``{\tt :}'', and dictionary words elsewhere. \key{add/move current file to front of agenda}{C-c [} \key{remove current file from your agenda}{C-c ]} -\key{cycle through agenda file list}{C-,} +\key{cycle through agenda file list}{C-'} \key{compile agenda for the current week}{C-c a a$^1$} \key{compile global TODO list}{C-c a t$^1$}