diff --git a/org b/org index 439d88aa2..0a546e8f7 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.69). + This manual is for Org-mode (version 4.70). Copyright (C) 2004, 2005, 2006, 2007 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.69). +This manual is for Org-mode (version 4.70). Copyright (C) 2004, 2005, 2006, 2007 Free Software Foundation @@ -138,8 +138,8 @@ Extended use of TODO keywords * Workflow states:: From TODO to DONE in steps * TODO types:: I do this, Fred the rest -* Per file keywords:: Different files, different requirements * Multiple sets in one file:: Mixing it all, and still finding your way +* Per file keywords:: Different files, different requirements Timestamps @@ -570,9 +570,9 @@ the visibility in the buffer. `C-c C-x b' Show the current subtree in an indirect buffer(3). With numerical - prefix ARG, go up to this level and then take that tree. If ARG - is negative, go up that many levels. With `C-u' prefix, do not - remove the previously used indirect buffer. + prefix ARG, go up to this level and then take that tree. If ARG is + negative, go up that many levels. With `C-u' prefix, do not remove + the previously used indirect buffer. When Emacs first visits an Org-mode file, the global state is set to OVERVIEW, i.e. only the top level headlines are visible. This can be @@ -590,7 +590,7 @@ basis by adding one of the following lines anywhere in the buffer: (2) see the option `org-cycle-global-at-bob'. (3) The indirect buffer (*note Indirect Buffers: (emacs)Indirect -Buffers.) will contain the entire buffer, but will be narrowed to the +Buffers.) will contain the entire buffer, but will be narrowed to the current tree. Editing the indirect buffer will also change the original buffer, but without affecting visibility in that buffer. @@ -2307,9 +2307,12 @@ The most important commands to work with TODO entries are: `C-c C-v' View TODO items in a _sparse tree_ (*note Sparse trees::). Folds the entire buffer, but shows all TODO items and the headings - hierarchy above them. With prefix arg, show also the DONE - entries. With numerical prefix N, show the tree for the Nth - keyword in the variable `org-todo-keywords'. + hierarchy above them. With prefix arg, search for a specific + TODO. You will be prompted for the keyword, and you can also give + a list of keywords like `kwd1|kwd2|...'. With numerical prefix N, + show the tree for the Nth keyword in the variable + `org-todo-keywords'. With two prefix args, find all TODO and DONE + entries. `C-c a t' Show the global TODO list. This collects the TODO items from all @@ -2326,10 +2329,9 @@ File: org, Node: TODO extensions, Next: Priorities, Prev: TODO basics, Up: T ================================= The default implementation of TODO entries is just two states: TODO and -DONE. You can, however, use the TODO feature for more complicated -things by configuring the variables `org-todo-keywords' and -`org-todo-interpretation'. Using special setup, you can even use TODO -keywords in different ways in different org files. +DONE. You can use the TODO feature for more complicated things by +configuring the variable `org-todo-keywords'. With special setup, the +TODO keyword system can work differently in different files. Note that tags are another way to classify headlines in general and TODO items in particular (*note Tags::). @@ -2338,8 +2340,8 @@ TODO items in particular (*note Tags::). * Workflow states:: From TODO to DONE in steps * TODO types:: I do this, Fred the rest -* Per file keywords:: Different files, different requirements * Multiple sets in one file:: Mixing it all, and still finding your way +* Per file keywords:: Different files, different requirements  File: org, Node: Workflow states, Next: TODO types, Prev: TODO extensions, Up: TODO extensions @@ -2347,46 +2349,52 @@ File: org, Node: Workflow states, Next: TODO types, Prev: TODO extensions, U 5.2.1 TODO keywords as workflow states -------------------------------------- -You can use TODO keywords to indicate different states in the process -of working on an item, for example: +You can use TODO keywords to indicate different _sequential_ states in +the process of working on an item, for example(1): - (setq org-todo-keywords '("TODO" "FEEDBACK" "VERIFY" "DONE") - org-todo-interpretation 'sequence) + (setq org-todo-keywords + '((sequence "TODO" "FEEDBACK" "VERIFY" "|" "DONE" "DELEGATED"))) - Changing these variables only becomes effective in a new Emacs -session. With this setup, the command `C-c C-t' will cycle an entry -from TODO to FEEDBACK, then to VERIFY, and finally to DONE. You may -also use a prefix argument to quickly select a specific state. For -example `C-3 C-c C-t' will change the state immediately to VERIFY. If -you define many keywords, you can use in-buffer completion (see *Note -Completion::) to insert these words into the buffer. Changing a todo -state can be logged with a timestamp, see *Note Tracking TODO state -changes:: for more information. + The vertical bar separates the TODO keywords (states that _need +action_) from the DONE states (which need _no further action_. If you +don't provide the separator bar, the last state is used as the DONE +state. With this setup, the command `C-c C-t' will cycle an entry from +TODO to FEEDBACK, then to VERIFY, and finally to DONE and DELEGATED. +You may also use a prefix argument to quickly select a specific state. +For example `C-3 C-c C-t' will change the state immediately to VERIFY. +If you define many keywords, you can use in-buffer completion (see +*Note Completion::) to insert these words into the buffer. Changing a +todo state can be logged with a timestamp, see *Note Tracking TODO +state changes:: for more information. + + ---------- Footnotes ---------- + + (1) Changing this variable only becomes effective after restarting +Org-mode in a buffer.  -File: org, Node: TODO types, Next: Per file keywords, Prev: Workflow states, Up: TODO extensions +File: org, Node: TODO types, Next: Multiple sets in one file, Prev: Workflow states, Up: TODO extensions 5.2.2 TODO keywords as types ---------------------------- The second possibility is to use TODO keywords to indicate different -types of action items. For example, you might want to indicate that -items are for "work" or "home". If you are into David Allen's _Getting -Things DONE_, you might want to use todo types `NEXTACTION', `WAITING', -`MAYBE'. Or, when you work with several people on a single project, -you might want to assign action items directly to persons, by using -their names as TODO keywords. This would be set up like this: +_types_ of action items. For example, you might want to indicate that +items are for "work" or "home". Or, when you work with several people +on a single project, you might want to assign action items directly to +persons, by using their names as TODO keywords. This would be set up +like this: - (setq org-todo-keywords '("Fred" "Sara" "Lucy" "Mike" "DONE") - org-todo-interpretation 'type) + (setq org-todo-keywords '((type "Fred" "Sara" "Lucy" "|" "DONE"))) In this case, different keywords do not indicate a sequence, but -rather different types. So it is normally not useful to change from -one type to another. Therefore, in this case the behavior of the -command `C-c C-t' is changed slightly(1). When used several times in -succession, it will still cycle through all names. But when you return +rather different types. So the normal work flow would be to assign a +task to a person, and later to mark it DONE. Org-mode supports this +style by adapting the workings of the command `C-c C-t'(1). When used +several times in succession, it will still cycle through all names, in +order to first select the right type for a task. But when you return to the item after some time and execute `C-c C-t' again, it will switch -from each name directly to DONE. Use prefix arguments or completion to +from any name directly to DONE. Use prefix arguments or completion to quickly select a specific name. You can also review the items of a specific TODO type in a sparse tree by using a numeric prefix to `C-c C-v'. For example, to see all things Lucy has to do, you would use @@ -2400,26 +2408,70 @@ global todo list: `C-3 C-c t'. buffers.  -File: org, Node: Per file keywords, Next: Multiple sets in one file, Prev: TODO types, Up: TODO extensions +File: org, Node: Multiple sets in one file, Next: Per file keywords, Prev: TODO types, Up: TODO extensions -5.2.3 Setting up TODO keywords for individual files ---------------------------------------------------- +5.2.3 Multiple keyword sets in one file +--------------------------------------- + +Sometimes you may want to use different sets of TODO keywords in +parallel. For example, you may want to have the basic `TODO'/`DONE', +but also a workflow for bug fixing, and a separate state indicating +that an item has been canceled (so it is not DONE, but also does not +require action). Your setup would then look like this: + + (setq org-todo-keywords + '((sequence "TODO" "|" "DONE") + (sequence "REPORT" "BUG" "KNOWNCAUSE" "|" "FIXED") + (sequence "|" "CANCELED"))) + + The keywords should all be different, this helps Org-mode to keep +track of which subsequence should be used for a given entry. In this +setup, `C-c C-t' only operates within a subsequence, so it switches from +`DONE' to (nothing) to `TODO', and from `FIXED' to (nothing) to +`REPORT'. Therefore you need a mechanism to initially select the +correct sequence. Besides the obvious ways like typing a keyword or +using completion, you may also apply the following commands: + +`C-S-' +`C-S-' + These keys jump from one TODO subset to the next. In the above + example, `C-S-' would jump from `TODO' or `DONE' to + `REPORT', and any of the words in the second row to `CANCELED'. + +`S-' +`S-' + `S-<>' and `S-<>' and walk through _all_ keywords + from all sets, so for example `S-<>' would switch from + `DONE' to `REPORT' in the example above. + + +File: org, Node: Per file keywords, Prev: Multiple sets in one file, Up: TODO extensions + +5.2.4 Setting up keywords for individual files +---------------------------------------------- It can be very useful to use different aspects of the TODO mechanism in -different files, which is not possible with the global settings -described above. For file-local settings, you need to add special -lines to the file which set the keywords and interpretation for that -file only. For example, to set one of the two examples discussed -above, you need one of the following lines, starting in column zero -anywhere in the file: +different files. For file-local settings, you need to add special lines +to the file which set the keywords and interpretation for that file +only. For example, to set one of the two examples discussed above, you +need one of the following lines, starting in column zero anywhere in the +file: - #+SEQ_TODO: TODO FEEDBACK VERIFY DONE - #+TYP_TODO: Fred Sara Lucy Mike DONE + #+SEQ_TODO: TODO FEEDBACK VERIFY | DONE CANCELED + or + #+TYP_TODO: Fred Sara Lucy Mike | DONE + + A setup for using several sets in parallel would be: + + #+SEQ_TODO: "TODO" "|" "DONE" + #+SEQ_TODO: "REPORT" "BUG" "KNOWNCAUSE" "|" "FIXED" + #+SEQ_TODO: "|" "CANCELED" To make sure you are using the correct keyword, type `#+' into the buffer and then use `M-' completion. - Remember that the last keyword must always mean that the item is DONE + Remember that the keywords after the vertical bar (or the last +keyword if no bar is there) must always mean that the item is DONE (although you may use a different word). After changing one of these lines, use `C-c C-c' with the cursor still in the line to make the changes known to Org-mode(1). @@ -2430,40 +2482,6 @@ changes known to Org-mode(1). after visiting a file. `C-c C-c' with the cursor in a line starting with `#+' is simply restarting Org-mode for the current buffer. - -File: org, Node: Multiple sets in one file, Prev: Per file keywords, Up: TODO extensions - -5.2.4 Multiple TODO keyword sets in one file --------------------------------------------- - -Sometimes you may want to use different sets of TODO keywords in the -same file. For example, you may want to have the basic `TODO'/`DONE', -but also a workflow for bug fixing. Your setup would then look like -this: - - #+SEQ_TODO: TODO DONE - #+SEQ_TODO: REPORT BUG KNOWNCAUSE RESOLVED - - The keywords should all be different, this helps Org-mode to keep -track of which subsequence should be used for a given entry. In this -setup, `C-c C-t' only operates within a subsequence, so it switches from -`DONE' to (nothing) to `TODO', and from `RESOLVED' to (nothing) to -`REPORT'. Therefore you need a mechanism to initially select the -correct sequence. Besides the obvious ways like typing a keyword or -using completion, you may also apply the following commands: - -`S-' -`S-' - `S-<>' and `S-<>' and walk through all keywords from - all sets, so for example `S-<>' would switch from `DONE' to - `REPORT' in the example above. - -`C-S-' -`C-S-' - These key jump from one TODO subset to the next. So `C-S-' - would jump from `TODO' to `REPORT' and from `KNOWNCAUSE' to `TODO' - in the above example. -  File: org, Node: Priorities, Next: Breaking down tasks, Prev: TODO extensions, Up: TODO items @@ -3509,13 +3527,14 @@ collected into a single place. `C-c a T' Like the above, but allows selection of a specific TODO keyword. You can also do this by specifying a prefix argument to `C-c a t'. - With a `C-u' prefix you are prompted for a keyword. With a - numeric prefix, the Nth keyword in `org-todo-keywords' is selected. The - `r' key in the agenda buffer regenerates it, and you can give a - prefix argument to this command to change the selected TODO - keyword, for example `3 r'. If you often need a search for a - specific keyword, define a custom command for it (*note Agenda - dispatcher::). + With a `C-u' prefix you are prompted for a keyword, and you may + also specify several keywords by separating them with `|' as + boolean OR operator. With a numeric prefix, the Nth keyword in + `org-todo-keywords' is selected. The `r' key in the agenda buffer + regenerates it, and you can give a prefix argument to this command + to change the selected TODO keyword, for example `3 r'. If you + often need a search for a specific keyword, define a custom + command for it (*note Agenda dispatcher::). Matching specific TODO keywords can also be done as part of a tags search (*note Tag searches::). @@ -4449,9 +4468,14 @@ File: org, Node: Export commands, Next: Quoting HTML tags, Prev: HTML export, `C-c C-e b' Export as HTML file and open it with a browser. +`C-c C-e H' + Export to a temporary buffer, do not create a file. + `C-c C-e v h' `C-c C-e v b' + +`C-c C-e v H' Export only the visible part of the document. In the exported version, the first 3 outline levels will become @@ -4648,22 +4672,23 @@ File: org, Node: Initial text, Next: Enhancing text, Prev: Comment lines, Up ------------------------------------- Org-mode normally ignores any text before the first headline when -exporting, because this region is often used for internal links to speed -up navigation etc. However, there are occasions when you might want to -have some text before the first headline, like a small intorduction, -special HTML code with a navigation bar, etc. You can ask to have this -part of the file exported as well by setting the variable +exporting, leaving this region for internal links to speed up navigation +etc. However, in publishing-oriented files, you might want to have some +text before the first headline, like a small introduction, special HTML +code with a navigation bar, etc. You can ask to have this part of the +file exported as well by setting the variable `org-export-skip-text-before-1st-heading' to `nil'. On a per-file basis, you can get the same effect with #+OPTIONS: skip:nil The text before the first headline will be fully processed (*note -Enhancing text::). If you need to include literal HTML, use the -special constructs described in *Note Quoting HTML tags::. The table of -contents is normally inserted directly before the first headline of the -file. If you would like to get it to a different location, insert the -string `[TABLE-OF-CONTENTS]' on a line by itself at the desired +Enhancing text::), and the first non-comment line becomes the title of +the exported document. If you need to include literal HTML, use the +special constructs described in *Note Quoting HTML tags::. The table +of contents is normally inserted directly before the first headline of +the file. If you would like to get it to a different location, insert +the string `[TABLE-OF-CONTENTS]' on a line by itself at the desired location. Finally, if you want to use the space before the first headline for @@ -4692,7 +4717,7 @@ formatted output. supports lists. See *Note Plain lists::. * You can make words *bold*, /italic/, _underlined_, `=code=', and - `+strikethrough+'. + even `+strikethrough+'(1). * A line consisting of only dashes, and at least 5 of them, will be exported as a horizontal line (`
' in HTML). @@ -4719,6 +4744,11 @@ they can all be turned off with corresponding variables. See the customization group `org-export-general', and the following section which explains how to set export options with special lines in a buffer. + ---------- Footnotes ---------- + + (1) but remember that strikethrough is typographically evil and +should never be used. +  File: org, Node: Export options, Prev: Enhancing text, Up: Text interpretation @@ -5414,14 +5444,14 @@ Default Alternative 1 Alternative 2 `S-' `C-c C-x c' `M-' `C-c C-x m' ` ' `M-S-' `C-c C-x M' -`S-' `C-c C-x +`S-' `C-c ' +`S-' `C-c ' +`S-' `C-c ' +`S-' `C-c ' +`C-S-'`C-c C-x ' -`S-' `C-c C-x +`C-S-'`C-c C-x ' -`S-' `C-c C-x - ' -`S-' `C-c C-x - '  File: org, Node: Interaction, Next: Bugs, Prev: TTY keys, Up: Miscellaneous @@ -6208,12 +6238,12 @@ Index * completion, of links: Handling links. (line 25) * completion, of option keywords <1>: Completion. (line 6) * completion, of option keywords <2>: Export options. (line 6) -* completion, of option keywords: Per file keywords. (line 17) +* completion, of option keywords: Per file keywords. (line 23) * completion, of tags <1>: Completion. (line 6) * completion, of tags: Setting tags. (line 11) * completion, of TeX symbols: Completion. (line 6) * completion, of TODO keywords <1>: Completion. (line 6) -* completion, of TODO keywords: Workflow states. (line 12) +* completion, of TODO keywords: Workflow states. (line 15) * constants, in calculations: References. (line 82) * constants.el: Cooperation. (line 14) * constcgs, STARTUP keyword: In-buffer settings. (line 52) @@ -6251,7 +6281,7 @@ Index * dispatching agenda commands: Agenda dispatcher. (line 6) * display changing, in agenda: Agenda commands. (line 65) * document structure: Document structure. (line 6) -* DONE, final TODO keyword: Per file keywords. (line 20) +* DONE, final TODO keyword: Per file keywords. (line 26) * dynamic blocks: Dynamic blocks. (line 6) * editing tables: Tables. (line 6) * editing, of table formulas: Editing and debugging formulas. @@ -6303,7 +6333,7 @@ Index * GNUS links: External links. (line 6) * hand-formatted lists: Enhancing text. (line 11) * headline levels: Export options. (line 25) -* headline levels, for exporting <1>: Export commands. (line 17) +* headline levels, for exporting <1>: Export commands. (line 22) * headline levels, for exporting: ASCII export. (line 18) * headline navigation: Motion. (line 6) * headline tagging: Tags. (line 6) @@ -6475,7 +6505,7 @@ Index * structure editing: Structure editing. (line 6) * structure of document: Document structure. (line 6) * sublevels, inclusion into tags match: Tag inheritance. (line 6) -* sublevels, inclusion into todo list: Global TODO list. (line 33) +* sublevels, inclusion into todo list: Global TODO list. (line 34) * subscript: Subscripts and Superscripts. (line 6) * subtree cycling: Visibility cycling. (line 10) @@ -6667,7 +6697,7 @@ Key Index * C-c a m: Tag searches. (line 12) * C-c a T: Global TODO list. (line 14) * C-c a t <1>: Global TODO list. (line 9) -* C-c a t: TODO basics. (line 33) +* C-c a t: TODO basics. (line 36) * C-c C-a: Visibility cycling. (line 33) * C-c C-b: Motion. (line 15) * C-c C-c <1>: Cooperation. (line 37) @@ -6688,6 +6718,7 @@ Key Index * C-c C-e a: ASCII export. (line 9) * C-c C-e b: Export commands. (line 7) * C-c C-e c: iCalendar export. (line 21) +* C-c C-e H: Export commands. (line 10) * C-c C-e h: Export commands. (line 6) * C-c C-e I: iCalendar export. (line 16) * C-c C-e i: iCalendar export. (line 14) @@ -6695,8 +6726,9 @@ Key Index * C-c C-e v <1>: XOXO export. (line 11) * C-c C-e v: Sparse trees. (line 41) * C-c C-e v a: ASCII export. (line 13) -* C-c C-e v b: Export commands. (line 10) -* C-c C-e v h: Export commands. (line 10) +* C-c C-e v b: Export commands. (line 13) +* C-c C-e v H: Export commands. (line 13) +* C-c C-e v h: Export commands. (line 13) * C-c C-e x: XOXO export. (line 10) * C-c C-f: Motion. (line 12) * C-c C-j: Motion. (line 21) @@ -6758,9 +6790,9 @@ Key Index * C-c ~: Cooperation. (line 48) * C-k: Agenda commands. (line 115) * C-S-: Multiple sets in one file. - (line 26) + (line 25) * C-S-: Multiple sets in one file. - (line 26) + (line 25) * C-TAB: ARCHIVE tag. (line 38) * C-u C-c *: Updating the table. (line 16) * C-u C-c .: Creating timestamps. (line 14) @@ -6802,7 +6834,7 @@ Key Index * M-: Structure editing. (line 24) * M- <1>: Completion. (line 10) * M- <2>: Setting tags. (line 6) -* M- <3>: Per file keywords. (line 17) +* M- <3>: Per file keywords. (line 23) * M-: Editing and debugging formulas. (line 64) * M- <1>: Editing and debugging formulas. @@ -6851,7 +6883,7 @@ Key Index * p: Agenda commands. (line 20) * q: Agenda commands. (line 227) * r <1>: Agenda commands. (line 80) -* r: Global TODO list. (line 20) +* r: Global TODO list. (line 22) * S: Agenda commands. (line 206) * s: Agenda commands. (line 87) * S- <1>: Agenda commands. (line 149) @@ -6867,7 +6899,7 @@ Key Index (line 42) * S- <3>: Creating timestamps. (line 51) * S- <4>: Multiple sets in one file. - (line 22) + (line 29) * S- <5>: TODO basics. (line 20) * S-: Editing and debugging formulas. (line 67) @@ -6878,7 +6910,7 @@ Key Index (line 39) * S- <3>: Creating timestamps. (line 51) * S- <4>: Multiple sets in one file. - (line 22) + (line 29) * S- <5>: TODO basics. (line 20) * S-: Editing and debugging formulas. (line 67) @@ -6915,172 +6947,174 @@ Node: Visibility cycling21720 Ref: Visibility cycling-Footnote-123934 Ref: Visibility cycling-Footnote-223992 Ref: Visibility cycling-Footnote-324042 -Node: Motion24311 -Node: Structure editing25095 -Node: Archiving27921 -Node: ARCHIVE tag28479 -Node: Moving subtrees30272 -Node: Sparse trees31583 -Ref: Sparse trees-Footnote-133715 -Ref: Sparse trees-Footnote-233897 -Node: Plain lists34012 -Ref: Plain lists-Footnote-137781 -Ref: Plain lists-Footnote-238139 -Node: Tables38323 -Node: Built-in table editor38837 -Node: Narrow columns45856 -Ref: Narrow columns-Footnote-147789 -Node: orgtbl-mode47835 -Node: The spreadsheet48639 -Node: References49726 -Ref: References-Footnote-153855 -Node: Formula syntax for Calc54144 -Node: Formula syntax for Lisp56610 -Node: Field formulas57879 -Node: Column formulas59187 -Node: Editing and debugging formulas60786 -Node: Updating the table64939 -Node: Advanced features65974 -Node: Hyperlinks70499 -Node: Link format71272 -Node: Internal links72565 -Ref: Internal links-Footnote-174490 -Node: Radio targets74622 -Node: External links75313 -Node: Handling links77717 -Ref: Handling links-Footnote-182827 -Ref: Handling links-Footnote-283064 -Node: Link abbreviations83138 -Node: Search options84817 -Ref: Search options-Footnote-186597 -Node: Custom searches86678 -Node: Remember87726 -Node: Setting up remember88713 -Node: Remember templates89295 -Ref: Remember templates-Footnote-192609 -Node: Storing notes92707 -Node: TODO items94515 -Node: TODO basics95498 -Node: TODO extensions97025 -Node: Workflow states97894 -Node: TODO types98879 -Ref: TODO types-Footnote-1100537 -Node: Per file keywords100619 -Ref: Per file keywords-Footnote-1101740 -Node: Multiple sets in one file101941 -Node: Priorities103299 -Node: Breaking down tasks104545 -Ref: Breaking down tasks-Footnote-1105065 -Node: Checkboxes105161 -Node: Timestamps107916 -Node: Time stamps108450 -Ref: Time stamps-Footnote-1111944 -Ref: Time stamps-Footnote-2112060 -Node: Creating timestamps112215 -Node: The date/time prompt114873 -Ref: The date/time prompt-Footnote-1116834 -Node: Custom time format116940 -Node: Repeating items118498 -Node: Progress logging120308 -Node: Closing items120954 -Ref: Closing items-Footnote-1121888 -Ref: Closing items-Footnote-2121957 -Node: Tracking TODO state changes122030 -Node: Clocking work time122886 -Ref: Clocking work time-Footnote-1126532 -Ref: Clocking work time-Footnote-2126610 -Node: Tags126736 -Node: Tag inheritance127498 -Node: Setting tags128435 -Ref: Setting tags-Footnote-1132958 -Ref: Setting tags-Footnote-2133070 -Node: Tag searches133153 -Node: Agenda views135864 -Node: Agenda files137809 -Ref: Agenda files-Footnote-1138775 -Ref: Agenda files-Footnote-2138924 -Node: Agenda dispatcher139117 -Node: Built-in agenda views140808 -Node: Weekly/Daily agenda141386 -Node: Global TODO list143515 -Node: Matching headline tags145688 -Node: Timeline146759 -Node: Stuck projects147425 -Node: Presentation and sorting149124 -Node: Categories149915 -Node: Time-of-day specifications150579 -Node: Sorting of agenda items152550 -Node: Agenda commands153832 -Node: Custom agenda views160561 -Node: Storing searches161236 -Node: Block agenda163148 -Node: Setting Options164378 -Node: Batch processing167090 -Node: Embedded LaTeX168220 -Ref: Embedded LaTeX-Footnote-1169312 -Node: Math symbols169502 -Node: Subscripts and Superscripts170267 -Node: LaTeX fragments171111 -Ref: LaTeX fragments-Footnote-1173219 -Node: Processing LaTeX fragments173481 -Node: CDLaTeX mode174427 -Ref: CDLaTeX mode-Footnote-1176911 -Node: Exporting177059 -Node: ASCII export178373 -Node: HTML export179663 -Node: Export commands180282 -Node: Quoting HTML tags181006 -Node: Links181636 -Node: Images182333 -Ref: Images-Footnote-1183204 -Node: CSS support183265 -Ref: CSS support-Footnote-1184584 -Node: XOXO export184697 -Node: iCalendar export185136 -Node: Text interpretation186355 -Node: Comment lines186897 -Node: Initial text187292 -Node: Enhancing text188900 -Node: Export options190718 -Node: Publishing192611 -Ref: Publishing-Footnote-1193407 -Node: Configuration193603 -Node: Project alist194321 -Node: Sources and destinations195387 -Node: Selecting files196117 -Node: Publishing action196865 -Node: Publishing options198098 -Node: Publishing links200250 -Node: Project page index201763 -Node: Sample configuration202541 -Node: Simple example203033 -Node: Complex example203706 -Node: Triggering publication205782 -Node: Miscellaneous206467 -Node: Completion207101 -Node: Customization208572 -Node: In-buffer settings209155 -Node: The very busy C-c C-c key213632 -Node: Clean view215276 -Node: TTY keys217853 -Node: Interaction219462 -Node: Cooperation219859 -Node: Conflicts222601 -Node: Bugs224193 -Node: Extensions and Hacking225689 -Node: Extensions226285 -Node: Tables in arbitrary syntax228232 -Node: Radio tables229309 -Node: A LaTeX example231812 -Ref: A LaTeX example-Footnote-1235458 -Ref: A LaTeX example-Footnote-2235606 -Node: Translator functions236041 -Ref: Translator functions-Footnote-1239150 -Node: Dynamic blocks239238 -Node: Special agenda views241210 -Ref: Special agenda views-Footnote-1243489 -Node: History and Acknowledgments243749 -Node: Index249609 -Node: Key Index280590 +Node: Motion24312 +Node: Structure editing25096 +Node: Archiving27922 +Node: ARCHIVE tag28480 +Node: Moving subtrees30273 +Node: Sparse trees31584 +Ref: Sparse trees-Footnote-133716 +Ref: Sparse trees-Footnote-233898 +Node: Plain lists34013 +Ref: Plain lists-Footnote-137782 +Ref: Plain lists-Footnote-238140 +Node: Tables38324 +Node: Built-in table editor38838 +Node: Narrow columns45857 +Ref: Narrow columns-Footnote-147790 +Node: orgtbl-mode47836 +Node: The spreadsheet48640 +Node: References49727 +Ref: References-Footnote-153856 +Node: Formula syntax for Calc54145 +Node: Formula syntax for Lisp56611 +Node: Field formulas57880 +Node: Column formulas59188 +Node: Editing and debugging formulas60787 +Node: Updating the table64940 +Node: Advanced features65975 +Node: Hyperlinks70500 +Node: Link format71273 +Node: Internal links72566 +Ref: Internal links-Footnote-174491 +Node: Radio targets74623 +Node: External links75314 +Node: Handling links77718 +Ref: Handling links-Footnote-182828 +Ref: Handling links-Footnote-283065 +Node: Link abbreviations83139 +Node: Search options84818 +Ref: Search options-Footnote-186598 +Node: Custom searches86679 +Node: Remember87727 +Node: Setting up remember88714 +Node: Remember templates89296 +Ref: Remember templates-Footnote-192610 +Node: Storing notes92708 +Node: TODO items94516 +Node: TODO basics95499 +Node: TODO extensions97198 +Node: Workflow states98017 +Ref: Workflow states-Footnote-199192 +Node: TODO types99285 +Ref: TODO types-Footnote-1100868 +Node: Multiple sets in one file100950 +Node: Per file keywords102561 +Ref: Per file keywords-Footnote-1103850 +Node: Priorities104051 +Node: Breaking down tasks105297 +Ref: Breaking down tasks-Footnote-1105817 +Node: Checkboxes105913 +Node: Timestamps108668 +Node: Time stamps109202 +Ref: Time stamps-Footnote-1112696 +Ref: Time stamps-Footnote-2112812 +Node: Creating timestamps112967 +Node: The date/time prompt115625 +Ref: The date/time prompt-Footnote-1117586 +Node: Custom time format117692 +Node: Repeating items119250 +Node: Progress logging121060 +Node: Closing items121706 +Ref: Closing items-Footnote-1122640 +Ref: Closing items-Footnote-2122709 +Node: Tracking TODO state changes122782 +Node: Clocking work time123638 +Ref: Clocking work time-Footnote-1127284 +Ref: Clocking work time-Footnote-2127362 +Node: Tags127488 +Node: Tag inheritance128250 +Node: Setting tags129187 +Ref: Setting tags-Footnote-1133710 +Ref: Setting tags-Footnote-2133822 +Node: Tag searches133905 +Node: Agenda views136616 +Node: Agenda files138561 +Ref: Agenda files-Footnote-1139527 +Ref: Agenda files-Footnote-2139676 +Node: Agenda dispatcher139869 +Node: Built-in agenda views141560 +Node: Weekly/Daily agenda142138 +Node: Global TODO list144267 +Node: Matching headline tags146539 +Node: Timeline147610 +Node: Stuck projects148276 +Node: Presentation and sorting149975 +Node: Categories150766 +Node: Time-of-day specifications151430 +Node: Sorting of agenda items153401 +Node: Agenda commands154683 +Node: Custom agenda views161412 +Node: Storing searches162087 +Node: Block agenda163999 +Node: Setting Options165229 +Node: Batch processing167941 +Node: Embedded LaTeX169071 +Ref: Embedded LaTeX-Footnote-1170163 +Node: Math symbols170353 +Node: Subscripts and Superscripts171118 +Node: LaTeX fragments171962 +Ref: LaTeX fragments-Footnote-1174070 +Node: Processing LaTeX fragments174332 +Node: CDLaTeX mode175278 +Ref: CDLaTeX mode-Footnote-1177762 +Node: Exporting177910 +Node: ASCII export179224 +Node: HTML export180514 +Node: Export commands181133 +Node: Quoting HTML tags181944 +Node: Links182574 +Node: Images183271 +Ref: Images-Footnote-1184142 +Node: CSS support184203 +Ref: CSS support-Footnote-1185522 +Node: XOXO export185635 +Node: iCalendar export186074 +Node: Text interpretation187293 +Node: Comment lines187835 +Node: Initial text188230 +Node: Enhancing text189904 +Ref: Enhancing text-Footnote-1191766 +Node: Export options191856 +Node: Publishing193749 +Ref: Publishing-Footnote-1194545 +Node: Configuration194741 +Node: Project alist195459 +Node: Sources and destinations196525 +Node: Selecting files197255 +Node: Publishing action198003 +Node: Publishing options199236 +Node: Publishing links201388 +Node: Project page index202901 +Node: Sample configuration203679 +Node: Simple example204171 +Node: Complex example204844 +Node: Triggering publication206920 +Node: Miscellaneous207605 +Node: Completion208239 +Node: Customization209710 +Node: In-buffer settings210293 +Node: The very busy C-c C-c key214770 +Node: Clean view216414 +Node: TTY keys218991 +Node: Interaction220601 +Node: Cooperation220998 +Node: Conflicts223740 +Node: Bugs225332 +Node: Extensions and Hacking226828 +Node: Extensions227424 +Node: Tables in arbitrary syntax229371 +Node: Radio tables230448 +Node: A LaTeX example232951 +Ref: A LaTeX example-Footnote-1236597 +Ref: A LaTeX example-Footnote-2236745 +Node: Translator functions237180 +Ref: Translator functions-Footnote-1240289 +Node: Dynamic blocks240377 +Node: Special agenda views242349 +Ref: Special agenda views-Footnote-1244628 +Node: History and Acknowledgments244888 +Node: Index250748 +Node: Key Index281729  End Tag Table diff --git a/org.el b/org.el index 9c544ee51..904c92175 100644 --- a/org.el +++ b/org.el @@ -5,7 +5,7 @@ ;; Author: Carsten Dominik ;; Keywords: outlines, hypermedia, calendar, wp ;; Homepage: http://www.astro.uva.nl/~dominik/Tools/org/ -;; Version: 4.69a +;; Version: 4.70 ;; ;; This file is part of GNU Emacs. ;; @@ -83,7 +83,7 @@ ;;; Version -(defconst org-version "4.69a" +(defconst org-version "4.70" "The version number of the file org.el.") (defun org-version () (interactive) @@ -1329,23 +1329,45 @@ When nil, new notes will be filed to the end of a file or entry." :tag "Org Progress" :group 'org-time) -(defcustom org-todo-keywords '("TODO" "DONE") - "List of TODO entry keywords. -\\By default, this is '(\"TODO\" \"DONE\"). The last entry in the list is -considered to mean that the entry is \"done\". All the other mean that -action is required, and will make the entry show up in todo lists, diaries -etc. -The command \\[org-todo] cycles an entry through these states, and an +(defcustom org-todo-keywords '((sequence "TODO" "DONE")) + "List of TODO entry keyword sequences and their interpretation. +\\This is a list of sequences. + +Each sequence starts with a symbol, either `sequence' or `type', +indicating if the keywords should be interpreted as a sequence of +action steps, or as different types of TODO items. The first +keywords are states requiring action - these states will select a headline +for inclusion into the global TODO list Org-mode produces. If one of +the \"keywords\" is the vertical bat \"|\" the remaining keywords +signify that no further action is necessary. If \"|\" is not found, +the last keyword is treated as the only DONE state of the sequence. + +The command \\[org-todo] cycles an entry through these states, and one additional state where no keyword is present. For details about this -cycling, see also the variable `org-todo-interpretation' -Changes become only effective after restarting Emacs. +cycling, see the manual. TODO keywords and interpretation can also be set on a per-file basis with -the special #+SEQ_TODO and #+TYP_TODO lines." +the special #+SEQ_TODO and #+TYP_TODO lines. + +For backward compatibility, this variable may also be just a list +of keywords - in this case the interptetation (sequence or type) will be +taken from the (otherwise obsolete) variable `org-todo-interpretation'." :group 'org-todo :group 'org-keywords - :type '(repeat (string :tag "Keyword"))) + :type '(choice + (repeat :tag "Old syntax, just keywords" + (string :tag "Keyword")) + (repeat :tag "New syntax" + (cons + (choice + :tag "Interpretation" + (const :tag "Sequence (cycling hits every state)" sequence) + (const :tag "Type (cycling directly to DONE)" type)) + (repeat + (string :tag "Keyword")))))) +(defvar org-todo-keywords-1 nil) +(make-variable-buffer-local 'org-todo-keywords-1) (defvar org-not-done-keywords nil) (make-variable-buffer-local 'org-not-done-keywords) (defvar org-done-keywords nil) @@ -1359,17 +1381,10 @@ the special #+SEQ_TODO and #+TYP_TODO lines." (defcustom org-todo-interpretation 'sequence "Controls how TODO keywords are interpreted. -This variable is only relevant if `org-todo-keywords' contains more than two -states. \\Possible values are `sequence' and `type'. - -When `sequence', \\[org-todo] will always switch to the next state in the -`org-todo-keywords' list. When `type', \\[org-todo] only cycles from state -to state when executed several times in direct succession. Otherwise, it -switches directly to DONE from any state. -See the manual for more information. - -TODO keywords and interpretation can also be set on a per-file basis with -the special #+SEQ_TODO and #+TYP_TODO lines." +This variable is in principle obsolete and is only used for +backward compatibility, if the interpretation of todo keywords is +not given already in `org-todo-keywords'. See that variable for +more information." :group 'org-todo :group 'org-keywords :type '(choice (const sequence) @@ -1694,7 +1709,7 @@ forth between agenda and calendar." :tag "Org Agenda Custom Commands" :group 'org-agenda) -(defcustom org-agenda-custom-commands '(("w" todo "WAITING")) +(defcustom org-agenda-custom-commands nil "Custom commands for the agenda. These commands will be offered on the splash screen displayed by the agenda dispatcher \\[org-agenda]. Each entry is a list like this: @@ -2942,15 +2957,6 @@ color of the frame." "Face for deadlines and TODO keywords." :group 'org-faces) -(defface org-headline-done ;; font-lock-string-face - (org-compatible-face - '((((class color) (min-colors 16) (background light)) (:foreground "RosyBrown")) - (((class color) (min-colors 16) (background dark)) (:foreground "LightSalmon")) - (((class color) (min-colors 8) (background light)) (:bold nil)))) - "Face used to indicate that a headline is DONE. -This face is only used if `org-fontify-done-headline' is set." - :group 'org-faces) - (defface org-archived ; similar to shadow (org-compatible-face '((((class color grayscale) (min-colors 88) (background light)) @@ -2999,7 +3005,17 @@ This face is only used if `org-fontify-done-headline' is set." (((class color) (min-colors 16) (background dark)) (:foreground "PaleGreen" :bold t)) (((class color) (min-colors 8)) (:foreground "green")) (t (:bold t)))) - "Face used for DONE." + "Face used for todo keywords that indicate DONE items." + :group 'org-faces) + +(defface org-headline-done ;; font-lock-string-face + (org-compatible-face + '((((class color) (min-colors 16) (background light)) (:foreground "RosyBrown")) + (((class color) (min-colors 16) (background dark)) (:foreground "LightSalmon")) + (((class color) (min-colors 8) (background light)) (:bold nil)))) + "Face used to indicate that a headline is DONE. +This face is only used if `org-fontify-done-headline' is set. If applies +to the part of the headline after the DONE keyword." :group 'org-faces) (defface org-table ;; font-lock-function-name-face @@ -3197,7 +3213,7 @@ means to push this value onto the list in the variable.") "Precompute regular expressions for current buffer." (when (org-mode-p) (org-set-local 'org-todo-kwd-alist nil) - (org-set-local 'org-todo-keywords nil) + (org-set-local 'org-todo-keywords-1 nil) (org-set-local 'org-done-keywords nil) (org-set-local 'org-todo-heads nil) (org-set-local 'org-todo-sets nil) @@ -3205,7 +3221,7 @@ means to push this value onto the list in the variable.") '("CATEGORY" "SEQ_TODO" "PRI_TODO" "TYP_TODO" "STARTUP" "ARCHIVE" "TAGS" "LINK"))) (splitre "[ \t]+") - kwds int key value cat arch tags links hw dw) + kwds key value cat arch tags links hw dws tail sep kws1) (save-excursion (save-restriction (widen) @@ -3218,11 +3234,9 @@ means to push this value onto the list in the variable.") (setq value (replace-match "" t t value))) (setq cat (intern value))) ((equal key "SEQ_TODO") - (push 'sequence int) - (push (org-split-string value splitre) kwds)) + (push (cons 'sequence (org-split-string value splitre)) kwds)) ((equal key "TYP_TODO") - (push 'type int) - (push (org-split-string value splitre) kwds)) + (push (cons 'type (org-split-string value splitre)) kwds)) ((equal key "TAGS") (setq tags (append tags (org-split-string value splitre)))) ((equal key "LINK") @@ -3252,21 +3266,27 @@ means to push this value onto the list in the variable.") (and arch (org-set-local 'org-archive-location arch)) (and links (setq org-link-abbrev-alist-local (nreverse links))) ;; Process the TODO keywords - (unless (and int kwds) + (unless kwds ;; Use the global values as if they had been given locally. - (setq kwds (list (default-value 'org-todo-keywords)) - int (list org-todo-interpretation))) - (setq int (nreverse int) kwds (nreverse kwds)) - (let (i k) - (while (setq i (pop int)) - (setq k (pop kwds) hw (car k) dw (org-last k)) + (setq kwds (default-value 'org-todo-keywords)) + (if (stringp (car kwds)) + (setq kwds (list (cons org-todo-interpretation + (default-value 'org-todo-keywords))))) + (setq kwds (reverse kwds))) + (setq kwds (nreverse kwds)) + (let (inter kws) + (while (setq kws (pop kwds)) + (setq inter (pop kws) sep (member "|" kws) + kws1 (delete "|" (copy-sequence kws)) + hw (car kws1) + dws (if sep (cdr sep) (last kws1)) + tail (list inter hw (car dws) (org-last dws))) (add-to-list 'org-todo-heads hw 'append) - (push k org-todo-sets) - (push dw org-done-keywords) - (mapc (lambda (x) (push (list x i hw dw) org-todo-kwd-alist)) k) - (setq org-todo-keywords (append org-todo-keywords k))) - (setq org-done-keywords (nreverse org-done-keywords) - org-todo-sets (nreverse org-todo-sets) + (push kws1 org-todo-sets) + (setq org-done-keywords (append org-done-keywords dws nil)) + (mapc (lambda (x) (push (cons x tail) org-todo-kwd-alist)) kws1) + (setq org-todo-keywords-1 (append org-todo-keywords-1 kws1 nil))) + (setq org-todo-sets (nreverse org-todo-sets) org-todo-kwd-alist (nreverse org-todo-kwd-alist))) ;; Process the tags. (when tags @@ -3288,13 +3308,13 @@ means to push this value onto the list in the variable.") ;; Compute the regular expressions and other local variables (if (not org-done-keywords) - (setq org-done-keywords (list (org-last org-todo-keywords)))) + (setq org-done-keywords (list (org-last org-todo-keywords-1)))) (setq org-ds-keyword-length (+ 2 (max (length org-deadline-string) (length org-scheduled-string))) org-not-done-keywords - (org-delete-all org-done-keywords (copy-sequence org-todo-keywords)) + (org-delete-all org-done-keywords (copy-sequence org-todo-keywords-1)) org-todo-regexp - (concat "\\<\\(" (mapconcat 'regexp-quote org-todo-keywords + (concat "\\<\\(" (mapconcat 'regexp-quote org-todo-keywords-1 "\\|") "\\)\\>") org-not-done-regexp (concat "\\<\\(" @@ -3302,7 +3322,7 @@ means to push this value onto the list in the variable.") "\\)\\>") org-todo-line-regexp (concat "^\\(\\*+\\)[ \t]*\\(?:\\(" - (mapconcat 'regexp-quote org-todo-keywords "\\|") + (mapconcat 'regexp-quote org-todo-keywords-1 "\\|") "\\)\\>\\)? *\\(.*\\)") org-nl-done-regexp (concat "[\r\n]\\*+[ \t]+" @@ -3310,7 +3330,7 @@ means to push this value onto the list in the variable.") "\\)" "\\>") org-todo-line-tags-regexp (concat "^\\(\\*+\\)[ \t]*\\(?:\\(" - (mapconcat 'regexp-quote org-todo-keywords "\\|") + (mapconcat 'regexp-quote org-todo-keywords-1 "\\|") "\\)\\>\\)? *\\(.*?\\([ \t]:[a-zA-Z0-9:_@]+:[ \t]*\\)?$\\)") org-looking-at-done-regexp (concat "^" "\\(?:" @@ -3550,6 +3570,7 @@ This variable is set by `org-before-change-function'. (defvar org-mode-hook nil) (defvar org-inhibit-startup nil) ; Dynamically-scoped param. (defvar org-agenda-keep-modes nil) ; Dynamically-scoped param. +(defvar org-table-buffer-is-an nil) ;;;###autoload @@ -4579,7 +4600,7 @@ state (TODO by default). Also with prefix arg, force first state." (if (or arg (not (match-beginning 2)) (member (match-string 2) org-done-keywords)) - (insert (car org-todo-keywords) " ") + (insert (car org-todo-keywords-1) " ") (insert (match-string 2) " ")))) ;;; Promotion and Demotion @@ -5303,8 +5324,12 @@ When nil, empty lines are part of the preceeding item." If the cursor is not in an item, throw an error." (interactive) (let ((pos (point)) - (limit (save-excursion (org-back-to-heading) - (beginning-of-line 2) (point))) + (limit (save-excursion + (condition-case nil + (progn + (org-back-to-heading) + (beginning-of-line 2) (point)) + (error (point-min))))) (ind-empty (if org-empty-line-terminates-plain-lists 0 10000)) ind ind1) (if (org-at-item-p) @@ -5564,14 +5589,14 @@ When called with prefix argument FIND-DONE, find whole trees without any open TODO items and archive them (after getting confirmation from the user). If the cursor is not at a headline when this comand is called, try all level 1 trees. If the cursor is on a headline, only try the direct children of -this heading. " +this heading." (interactive "P") (if find-done (org-archive-all-done) ;; Save all relevant TODO keyword-relatex variables (let ((tr-org-todo-line-regexp org-todo-line-regexp) ; keep despite compiler - (tr-org-todo-keywords org-todo-keywords) + (tr-org-todo-keywords-1 org-todo-keywords-1) (tr-org-todo-kwd-alist org-todo-kwd-alist) (tr-org-done-keywords org-done-keywords) (tr-org-todo-regexp org-todo-regexp) @@ -5612,7 +5637,8 @@ this heading. " ;; Enforce org-mode for the archive buffer (if (not (org-mode-p)) ;; Force the mode for future visits. - (let ((org-insert-mode-line-in-empty-file t)) + (let ((org-insert-mode-line-in-empty-file t) + (org-inhibit-startup t)) (call-interactively 'org-mode))) (when newfile-p (goto-char (point-max)) @@ -5620,7 +5646,7 @@ this heading. " (buffer-file-name this-buffer)))) ;; Force the TODO keywords of the original buffer (let ((org-todo-line-regexp tr-org-todo-line-regexp) - (org-todo-keywords tr-org-todo-keywords) + (org-todo-keywords-1 tr-org-todo-keywords-1) (org-todo-kwd-alist tr-org-todo-kwd-alist) (org-done-keywords tr-org-done-keywords) (org-todo-regexp tr-org-todo-regexp) @@ -5652,10 +5678,10 @@ this heading. " (goto-char (point-max)) (insert "\n")) ;; Paste (org-paste-subtree (org-get-legal-level level 1)) - ;; Mark the entry as done, i.e. set to last work in org-todo-keywords + ;; Mark the entry as done, i.e. set to last word in org-todo-keywords-1 FIXME: not right anymore!!!!!!! (if org-archive-mark-done (let (org-log-done) - (org-todo (length org-todo-keywords)))) + (org-todo (length org-todo-keywords-1)))) ;; Move cursor to right after the TODO keyword (when org-archive-stamp-time (beginning-of-line 1) @@ -7118,8 +7144,8 @@ the table and kill the editing buffer." (defun org-trim (s) "Remove whitespace at beginning and end of string." - (if (string-match "^[ \t]+" s) (setq s (replace-match "" t t s))) - (if (string-match "[ \t]+$" s) (setq s (replace-match "" t t s))) + (if (string-match "^[ \t\n\r]+" s) (setq s (replace-match "" t t s))) + (if (string-match "[ \t\n\r]+$" s) (setq s (replace-match "" t t s))) s) (defun org-wrap (string &optional width lines) @@ -8137,7 +8163,10 @@ Parameters get priority." entry s type title) (switch-to-buffer-other-window "*Edit Formulas*") (erase-buffer) - (fundamental-mode) + ;; Keep global-font-lock-mode from turning on font-lock-mode + (let ((font-lock-global-modes '(not fundamental-mode))) + (fundamental-mode)) + (org-set-local 'font-lock-global-modes (list 'not major-mode)) (org-set-local 'org-pos pos) (org-set-local 'org-window-configuration wc) (use-local-map org-table-fedit-map) @@ -8344,7 +8373,6 @@ a translation reference." (goto-char pos) (org-table-toggle-coordinate-overlays))))) -(defvar org-table-buffer-is-an nil) (defun org-table-fedit-finish (&optional arg) "Parse the buffer for formula definitions and install them. With prefix ARG, apply the new formulas to the table." @@ -11210,7 +11238,7 @@ At all other locations, this simply calls `ispell-complete-word'." ((string-match "\\`\\*+[ \t]*\\'" (buffer-substring (point-at-bol) beg)) (setq type :todo) - (mapcar 'list org-todo-keywords)) + (mapcar 'list org-todo-keywords-1)) (searchhead (setq type :searchhead) (save-excursion @@ -11310,29 +11338,31 @@ For calling through lisp, arg is also interpreted in the following way: (looking-at " *")) (let* ((this (match-string 1)) (head (org-get-todo-sequence-head this)) - (interpret (nth 1 (assoc head org-todo-kwd-alist))) - (done-word (nth 3 (assoc head org-todo-kwd-alist))) + (ass (assoc head org-todo-kwd-alist)) + (interpret (nth 1 ass)) + (done-word (nth 3 ass)) + (final-done-word (nth 4 ass)) (last-state (or this "")) (completion-ignore-case t) - (member (member this org-todo-keywords)) + (member (member this org-todo-keywords-1)) (tail (cdr member)) (state (cond ((equal arg '(4)) ;; Read a state with completion (completing-read "State: " (mapcar (lambda(x) (list x)) - org-todo-keywords) + org-todo-keywords-1) nil t)) ((eq arg 'right) (if this (if tail (car tail) nil) - (car org-todo-keywords))) + (car org-todo-keywords-1))) ((eq arg 'left) - (if (equal member org-todo-keywords) + (if (equal member org-todo-keywords-1) nil (if this - (nth (- (length org-todo-keywords) (length tail) 2) - org-todo-keywords) - (org-last org-todo-keywords)))) + (nth (- (length org-todo-keywords-1) (length tail) 2) + org-todo-keywords-1) + (org-last org-todo-keywords-1)))) (arg ;; user or caller requests a specific state (cond @@ -11346,11 +11376,11 @@ For calling through lisp, arg is also interpreted in the following way: (let ((org-todo-heads (reverse org-todo-heads))) (or (car (cdr (member head org-todo-heads))) (car org-todo-heads)))) - ((car (member arg org-todo-keywords))) + ((car (member arg org-todo-keywords-1))) ((nth (1- (prefix-numeric-value arg)) - org-todo-keywords)))) - ((null member) (or head (car org-todo-keywords))) - ((member this org-done-keywords) nil) ;; -> make empty + org-todo-keywords-1)))) + ((null member) (or head (car org-todo-keywords-1))) + ((equal this final-done-word) nil) ;; -> make empty ((null tail) nil) ;; -> first entry ((eq interpret 'sequence) (car tail)) @@ -11369,7 +11399,7 @@ For calling through lisp, arg is also interpreted in the following way: (mapconcat 'identity (assoc state org-todo-sets) " "))) (setq org-last-todo-state-is-todo (not (member state org-done-keywords))) - (when org-log-done + (when (and org-log-done (not (memq arg '(nextset previousset)))) (setq dostates (and (eq interpret 'sequence) (listp org-log-done) (memq 'state org-log-done))) (cond @@ -11412,8 +11442,8 @@ right sequence." (setq p (next-single-property-change (point-at-bol) 'org-todo-head nil (point-at-eol))) (get-text-property p 'org-todo-head)))) - ((not (member kwd org-todo-keywords)) - (car org-todo-keywords)) + ((not (member kwd org-todo-keywords-1)) + (car org-todo-keywords-1)) (t (nth 2 (assoc kwd org-todo-kwd-alist)))))) (defun org-get-repeat () @@ -11475,15 +11505,20 @@ The tree will show the lines where the regexp matches, and all higher headlines above the match. With \\[universal-argument] prefix, also show the DONE entries. With a numeric prefix N, construct a sparse tree for the Nth element -of `org-todo-keywords'." +of `org-todo-keywords-1'." (interactive "P") (let ((case-fold-search nil) (kwd-re (cond ((null arg) org-not-done-regexp) - ((equal arg '(4)) org-todo-regexp) - ((<= (prefix-numeric-value arg) (length org-todo-keywords)) + ((equal arg '(4)) + (let ((kwd (completing-read "Keyword (or KWD1|KWD2|...): " + (mapcar 'list org-todo-keywords-1)))) + (concat "\\(" + (mapconcat 'identity (org-split-string kwd "|") "\\|") + "\\)\\>"))) + ((<= (prefix-numeric-value arg) (length org-todo-keywords-1)) (regexp-quote (nth (1- (prefix-numeric-value arg)) - org-todo-keywords))) + org-todo-keywords-1))) (t (error "Invalid prefix argument: %s" arg))))) (message "%d TODO entries found" (org-occur (concat "^" outline-regexp " +" kwd-re ))))) @@ -11833,7 +11868,7 @@ inclusion. When TODO-ONLY is non-nil, only lines with a TODO keyword are included in the output." (let* ((re (concat "[\n\r]" outline-regexp " *\\(\\<\\(" (mapconcat 'regexp-quote - (nreverse (cdr (reverse org-todo-keywords))) + (nreverse (cdr (reverse org-todo-keywords-1))) "\\|") "\\>\\)\\)? *\\(.*?\\)\\(:[A-Za-z_@0-9:]+:\\)?[ \t]*$")) (props (list 'face nil @@ -13385,6 +13420,8 @@ The following commands are available: (setq org-agenda-undo-list nil org-agenda-pending-undo-list nil) (setq major-mode 'org-agenda-mode) + ;; Keep global-font-lock-mode from turning on font-lock-mode + (org-set-local 'font-lock-global-modes (list 'not major-mode)) (setq mode-name "Org-Agenda") (use-local-map org-agenda-mode-map) (easy-menu-add org-agenda-menu) @@ -13429,6 +13466,8 @@ The following commands are available: (define-key org-agenda-mode-map "\C-c\C-o" 'org-agenda-open-link) (define-key org-agenda-mode-map " " 'org-agenda-show) (define-key org-agenda-mode-map "\C-c\C-t" 'org-agenda-todo) +(define-key org-agenda-mode-map [(control shift right)] 'org-agenda-todo-nextset) +(define-key org-agenda-mode-map [(control shift left)] 'org-agenda-todo-previousset) (define-key org-agenda-mode-map "\C-c\C-xb" 'org-agenda-tree-to-indirect-buffer) (define-key org-agenda-mode-map "b" 'org-agenda-tree-to-indirect-buffer) (define-key org-agenda-mode-map "o" 'delete-other-windows) @@ -14161,9 +14200,13 @@ When a buffer is unmodified, it is just killed. When modified, it is saved "Get the table of categories and positions in current buffer." (let (tbl) (save-excursion - (goto-char (point-min)) - (while (re-search-forward "\\(^\\|\r\\)#\\+CATEGORY:[ \t]*\\(.*\\)" nil t) - (push (cons (point) (org-trim (match-string 2))) tbl))) + (save-restriction + (widen) + (goto-char (point-min)) + (while (re-search-forward "^#\\+CATEGORY:[ \t]*\\(.*\\)" + nil t) + (push (cons (match-beginning 1) + (org-trim (match-string 1))) tbl)))) tbl)) (defun org-get-category (&optional pos) @@ -14458,28 +14501,29 @@ NDAYS defaults to `org-agenda-ndays'." The prefix arg can be used to select a specific TODO keyword and limit the list to these. When using \\[universal-argument], you will be prompted for a keyword. A numeric prefix directly selects the Nth keyword in -`org-todo-keywords'." +`org-todo-keywords-1'." (interactive "P") (require 'calendar) (org-compile-prefix-format 'todo) (org-set-sorting-strategy 'todo) (let* ((today (time-to-days (current-time))) (date (calendar-gregorian-from-absolute today)) - (kwds org-todo-keywords) + (kwds org-todo-keywords-1) (completion-ignore-case t) (org-select-this-todo-keyword (if (stringp arg) arg (and arg (integerp arg) (> arg 0) - (nth (1- arg) org-todo-keywords)))) + (nth (1- arg) org-todo-keywords-1)))) rtn rtnall files file pos) (when (equal arg '(4)) (setq org-select-this-todo-keyword - (completing-read "Keyword: " (mapcar 'list org-todo-keywords) - nil t))) + (completing-read "Keyword (or KWD1|K2D2|...): " + (mapcar 'list org-todo-keywords-1) + nil nil))) (and (equal 0 arg) (setq org-select-this-todo-keyword nil)) (org-prepare-agenda) (org-set-local 'org-last-arg arg) - (org-set-local 'org-todo-keywords kwds) + (org-set-local 'org-todo-keywords-1 kwds) (setq org-agenda-redo-command '(org-todo-list (or current-prefix-arg org-last-arg))) (setq files (org-agenda-files) @@ -14505,7 +14549,7 @@ for a keyword. A numeric prefix directly selects the Nth keyword in (let ((n 0)) (mapconcat (lambda (x) (format "(%d)%s" (setq n (1+ n)) x)) - org-todo-keywords " ")) + org-todo-keywords-1 " ")) "\n")) (add-text-properties pos (1- (point)) (list 'face 'org-level-3))) (when rtnall @@ -14883,7 +14927,8 @@ the documentation of `org-diary'." ;; FIXME: get rid of the \n at some point but watch out (regexp (concat "[\n\r]\\*+ *\\(" (if org-select-this-todo-keyword - (concat "\\<\\(" org-select-this-todo-keyword + (concat "\\<\\(" + (mapconcat 'identity (org-split-string org-select-this-todo-keyword "|") "\\|") "\\)\\>") org-not-done-regexp) "[^\n\r]*\\)")) @@ -15926,6 +15971,16 @@ dedicated frame)." "Marker pointing to the headline that last changed its TODO state by a remote command from the agenda.") +(defun org-agenda-todo-nextset () + "Switch TODO entry to next sequence." + (interactive) + (org-agenda-todo 'nextset)) + +(defun org-agenda-todo-previousset () + "Switch TODO entry to previous sequence." + (interactive) + (org-agenda-todo 'previousset)) + (defun org-agenda-todo (&optional arg) "Cycle TODO state of line at point, also in Org-mode file. This changes the line at point, all other lines in the agenda referring to @@ -16839,6 +16894,7 @@ The images can be removed again with \\[org-ctrl-c-ctrl-c]." \[a] export as ASCII \[h] export as HTML +\[H] export as HTML to temporary buffer \[b] export as HTML and browse immediately \[x] export as XOXO @@ -16856,6 +16912,7 @@ The images can be removed again with \\[org-ctrl-c-ctrl-c]." (?a . org-export-as-ascii) (?h . org-export-as-html) (?b . org-export-as-html-and-open) + (?H . org-export-as-html-to-buffer) (?x . org-export-as-xoxo) (?i . org-export-icalendar-this-file) (?I . org-export-icalendar-all-agenda-files) @@ -17187,11 +17244,16 @@ translations. There is currently no way for users to extend this.") (re-quote (concat "^\\*+[ \t]+" org-quote-string "\\>")) (htmlp (plist-get parameters :for-html)) (outline-regexp "\\*+") - rtn) + rtn p) (save-excursion (set-buffer (get-buffer-create " org-mode-tmp")) (erase-buffer) (insert string) + ;; Remove license-to-kill stuff + (while (setq p (text-property-any (point-min) (point-max) + :org-license-to-kill t)) + (delete-region p (next-single-property-change p :org-license-to-kill))) + (let ((org-inhibit-startup t)) (org-mode)) (untabify (point-min) (point-max)) @@ -17318,6 +17380,18 @@ translations. There is currently no way for users to extend this.") (kill-buffer " org-mode-tmp") rtn)) +(defun org-export-grab-title-from-buffer () + "Get a title for the current document, from looking at the buffer." + (save-excursion + (goto-char (point-min)) + (let ((end (save-excursion (outline-next-heading) (point)))) + (when (re-search-forward "^[ \t]*[^# \t\r\n].*\n" end t) + ;; Mark the line so that it will not be exported as normal text. + (add-text-properties (match-beginning 0) (match-end 0) + (list :org-license-to-kill t)) + ;; Return the title string + (org-trim (match-string 0)))))) + (defun org-solidify-link-text (s &optional alist) "Take link text and make a safe target out of it." (save-match-data @@ -17394,14 +17468,6 @@ underlined headlines. The default is 3." (if (org-region-active-p) (region-beginning) (point-min)) (if (org-region-active-p) (region-end) (point-max)))) (custom-times org-display-custom-times) - (lines (org-skip-comments - (org-split-string - (org-cleaned-string-for-export - region - :skip-before-1st-heading - (plist-get opt-plist :skip-before-1st-heading) - :add-text (plist-get opt-plist :text)) - "[\r\n]"))) (org-ascii-current-indentation '(0 . 0)) (level 0) line txt (umax nil) @@ -17419,6 +17485,9 @@ underlined headlines. The default is 3." (time (format-time-string "%X" (org-current-time))) (author (plist-get opt-plist :author)) (title (or (plist-get opt-plist :title) + (and (not + (plist-get opt-plist :skip-before-1st-heading)) + (org-export-grab-title-from-buffer)) (file-name-sans-extension (file-name-nondirectory buffer-file-name)))) (email (plist-get opt-plist :email)) @@ -17427,7 +17496,17 @@ underlined headlines. The default is 3." ; (quote-re (concat "^\\(\\*+\\)\\([ \t]*" org-quote-string "\\>\\)")) (todo nil) (lang-words nil) - thetoc first-heading-pos) + (lines (org-skip-comments + (org-split-string + (org-cleaned-string-for-export + region + :skip-before-1st-heading + (plist-get opt-plist :skip-before-1st-heading) + :add-text (plist-get opt-plist :text)) + "[\r\n]"))) + thetoc have-headings first-heading-pos) + + (remove-text-properties (point-min) (point-max) '(:org-license-to-kill t)) (setq org-last-level 1) (org-init-section-numbers) @@ -17473,6 +17552,7 @@ underlined headlines. The default is 3." line) ;; This is a headline (progn + (setq have-headings t) (setq level (- (match-end 1) (match-beginning 1)) level (org-tr-level level) txt (match-string 3 line) @@ -17507,7 +17587,7 @@ underlined headlines. The default is 3." (setq org-last-level level)) )))) lines) - (setq thetoc (nreverse thetoc)))) + (setq thetoc (if have-headings (nreverse thetoc) nil)))) (org-init-section-numbers) (while (setq line (pop lines)) @@ -17636,7 +17716,7 @@ continue to use it. The prefix arg ARG is passed through to the exporting command." (interactive (list (progn - (message "Export visible: [a]SCII [h]tml [b]rowse HTML [x]OXO [ ]keep buffer") + (message "Export visible: [a]SCII [h]tml [b]rowse HTML [H]uffer with HTML [x]OXO [ ]keep buffer") (read-char-exclusive)) current-prefix-arg)) (if (not (member type '(?a ?\C-a ?b ?\C-b ?h ?x ?\ ))) @@ -17647,6 +17727,7 @@ command." (?b . org-export-as-html-and-open) (?\C-b . org-export-as-html-and-open) (?h . org-export-as-html) + (?H . org-export-as-html-to-buffer) (?x . org-export-as-xoxo))))) (keepp (equal type ?\ )) (file buffer-file-name) @@ -17818,14 +17899,23 @@ emacs --batch --visit=MyFile --funcall org-export-as-html-batch" (org-export-as-html org-export-headline-levels 'hidden)) -(defun org-export-as-html (arg &optional hidden ext-plist) +(defun org-export-as-html-to-buffer (arg) + "Call `org-exort-as-html` with output to a temporary buffer. +No file is created. The prefix ARG is passed through to `org-export-as-html'." + (interactive "P") + (org-export-as-html arg nil nil t) + (switch-to-buffer-other-window "*Org HTML Export*")) + +(defun org-export-as-html (arg &optional hidden ext-plist temp-buffer-only) "Export the outline as a pretty HTML file. -If there is an active region, export only the region. -The prefix ARG specifies how many levels of the outline should become -headlines. The default is 3. Lower levels will become bulleted lists. -When HIDDEN is non-nil, don't display the HTML buffer. +If there is an active region, export only the region. The prefix +ARG specifies how many levels of the outline should become +headlines. The default is 3. Lower levels will become bulleted +lists. When HIDDEN is non-nil, don't display the HTML buffer. EXT-PLIST is a property list with external parameters overriding -org-mode's default settings, but still inferior to file-local settings." +org-mode's default settings, but still inferior to file-local +settings. Wehn TEMP-BUFFER-ONLY is non-nil, export to a buffer not +associated with a file." (interactive "P") (message "Exporting...") (setq-default org-todo-line-regexp org-todo-line-regexp) @@ -17838,7 +17928,7 @@ org-mode's default settings, but still inferior to file-local settings." (style (plist-get opt-plist :style)) (link-validate (plist-get opt-plist :link-validation-function)) - valid thetoc first-heading-pos + valid thetoc have-headings first-heading-pos (odd org-odd-levels-only) (region-p (org-region-active-p)) (region @@ -17849,19 +17939,6 @@ org-mode's default settings, but still inferior to file-local settings." ;; routines below. (org-current-export-dir (org-export-directory :html opt-plist)) (org-current-export-file buffer-file-name) - (lines - (org-skip-comments (org-split-string - (org-cleaned-string-for-export - region - :emph-multiline t - :for-html t - :skip-before-1st-heading - (plist-get opt-plist :skip-before-1st-heading) - :add-text - (plist-get opt-plist :text) - :LaTeX-fragments - (plist-get opt-plist :LaTeX-fragments)) - "[\r\n]"))) (level 0) (line "") (origline "") txt todo (umax nil) (umax-toc nil) @@ -17871,12 +17948,17 @@ org-mode's default settings, but still inferior to file-local settings." (file-name-nondirectory buffer-file-name)) ".html")) (current-dir (file-name-directory buffer-file-name)) - (buffer (find-file-noselect filename)) + (buffer (if temp-buffer-only + (get-buffer-create "*Org HTML Export*") + (find-file-noselect filename))) (org-levels-open (make-vector org-level-max nil)) (date (format-time-string "%Y/%m/%d" (current-time))) (time (format-time-string "%X" (org-current-time))) (author (plist-get opt-plist :author)) (title (or (plist-get opt-plist :title) + (and (not + (plist-get opt-plist :skip-before-1st-heading)) + (org-export-grab-title-from-buffer)) (file-name-sans-extension (file-name-nondirectory buffer-file-name)))) (quote-re0 (concat "^[ \t]*" org-quote-string "\\>")) @@ -17900,11 +17982,27 @@ org-mode's default settings, but still inferior to file-local settings." (charset (and coding-system (fboundp 'coding-system-get) (coding-system-get coding-system 'mime-charset))) + (lines + (org-skip-comments (org-split-string + (org-cleaned-string-for-export + region + :emph-multiline t + :for-html t + :skip-before-1st-heading + (plist-get opt-plist :skip-before-1st-heading) + :add-text + (plist-get opt-plist :text) + :LaTeX-fragments + (plist-get opt-plist :LaTeX-fragments)) + "[\r\n]"))) table-open type table-buffer table-orig-buffer ind start-is-num starter didclose rpl path desc descp desc1 desc2 link ) + + (remove-text-properties (point-min) (point-max) '(:org-license-to-kill t)) + (message "Exporting...") (setq org-last-level 1) @@ -17955,8 +18053,8 @@ lang=\"%s\" xml:lang=\"%s\"> (insert (or (plist-get opt-plist :preamble) "")) (when (plist-get opt-plist :auto-preamble) - (if title (insert (format org-export-html-title-format - (org-html-expand title))))) + (if title (insert (format org-export-html-title-format + (org-html-expand title))))) (if org-export-with-toc (progn @@ -17971,6 +18069,7 @@ lang=\"%s\" xml:lang=\"%s\"> (if (string-match org-todo-line-regexp line) ;; This is a headline (progn + (setq have-headings t) (setq level (- (match-end 1) (match-beginning 1)) level (org-tr-level level) txt (save-match-data @@ -18035,7 +18134,7 @@ lang=\"%s\" xml:lang=\"%s\"> (while (> org-last-level 0) (setq org-last-level (1- org-last-level)) (push "\n\n" thetoc)) - (setq thetoc (nreverse thetoc)))) + (setq thetoc (if have-headings (nreverse thetoc) nil)))) (setq head-count 0) (org-init-section-numbers) @@ -18366,11 +18465,10 @@ lang=\"%s\" xml:lang=\"%s\"> (goto-char (point-min)) (while (re-search-forward "
  • [ \r\n\t]*
    • \n?" nil t) (replace-match "")) - (save-buffer) + (or temp-buffer-only (save-buffer)) (goto-char (point-min)) (message "Exporting... done")))) - (defun org-format-table-html (lines olines) "Find out which HTML converter to use and return the HTML code." (if (string-match "^[ \t]*|" (car lines)) @@ -19079,10 +19177,12 @@ The XOXO buffer is named *xoxo-*" (define-key org-mode-map "\C-c\C-xR" 'org-shiftmetaright) (define-key org-mode-map "\C-c\C-xU" 'org-shiftmetaup) (define-key org-mode-map "\C-c\C-xD" 'org-shiftmetadown) - (define-key org-mode-map [?\C-c ?\C-x (up)] 'org-shiftup) - (define-key org-mode-map [?\C-c ?\C-x (down)] 'org-shiftdown) - (define-key org-mode-map [?\C-c ?\C-x (left)] 'org-shiftleft) - (define-key org-mode-map [?\C-c ?\C-x (right)] 'org-shiftright)) + (define-key org-mode-map [?\C-c (up)] 'org-shiftup) + (define-key org-mode-map [?\C-c (down)] 'org-shiftdown) + (define-key org-mode-map [?\C-c (left)] 'org-shiftleft) + (define-key org-mode-map [?\C-c (right)] 'org-shiftright) + (define-key org-mode-map [?\C-c ?\C-x (right)] 'org-shiftcontrolright) + (define-key org-mode-map [?\C-c ?\C-x (left)] 'org-shiftcontrolleft)) ;; All the other keys @@ -19694,7 +19794,9 @@ See the individual commands for more information." ("Select keyword" ["Next keyword" org-shiftright (org-on-heading-p)] ["Previous keyword" org-shiftleft (org-on-heading-p)] - ["Complete Keyword" org-complete (assq :todo-keyword (org-context))]) + ["Complete Keyword" org-complete (assq :todo-keyword (org-context))] + ["Next keyword set" org-shiftcontrolright (and (> (length org-todo-sets) 1) (org-on-heading-p))] + ["Previous keyword set" org-shiftcontrolright (and (> (length org-todo-sets) 1) (org-on-heading-p))]) ["Show TODO Tree" org-show-todo-tree t] ["Global TODO list" org-todo-list t] "--" @@ -20194,6 +20296,9 @@ to a visible line beginning. This makes the function of C-a more intuitive." (defalias 'org-back-to-heading 'outline-back-to-heading) (defalias 'org-on-heading-p 'outline-on-heading-p) +(defalias 'org-at-heading-p 'outline-on-heading-p) +(defun org-at-heading-or-item-p () + (or (org-on-heading-p) (org-at-item-p))) (defun org-on-target-p () (or (org-in-regexp org-radio-target-regexp) @@ -20361,7 +20466,6 @@ Show the heading too, if it is currently invisible." ;;;; Experimental code - ;;;; Finish up (provide 'org) @@ -20370,4 +20474,3 @@ Show the heading too, if it is currently invisible." ;; arch-tag: e77da1a7-acc7-4336-b19e-efa25af3f9fd ;;; org.el ends here - diff --git a/org.pdf b/org.pdf index f3a055ca1..0c91f6ef6 100644 Binary files a/org.pdf and b/org.pdf differ diff --git a/org.texi b/org.texi index faa54fd53..95708023f 100644 --- a/org.texi +++ b/org.texi @@ -3,7 +3,7 @@ @setfilename ../info/org @settitle Org Mode Manual -@set VERSION 4.69 +@set VERSION 4.70 @set DATE March 2007 @dircategory Emacs @@ -169,8 +169,8 @@ Extended use of TODO keywords * Workflow states:: From TODO to DONE in steps * TODO types:: I do this, Fred the rest -* Per file keywords:: Different files, different requirements * Multiple sets in one file:: Mixing it all, and still finding your way +* Per file keywords:: Different files, different requirements Timestamps @@ -663,13 +663,19 @@ level, all sibling headings. @kindex C-c C-x b @item C-c C-x b Show the current subtree in an indirect buffer@footnote{The indirect -buffer (@pxref{Indirect Buffers,Indirect Buffers,Indirect -Buffers,emacs,GNU Emacs Manual}) will contain the entire buffer, but -will be narrowed to the current tree. Editing the indirect buffer will -also change the original buffer, but without affecting visibility in -that buffer.}. With numerical prefix ARG, go up to this level and then -take that tree. If ARG is negative, go up that many levels. With -@kbd{C-u} prefix, do not remove the previously used indirect buffer. +buffer +@ifinfo +(@pxref{Indirect Buffers,,,emacs,GNU Emacs Manual}) +@end ifinfo +@ifnotinfo +(see the Emacs manual for more information about indirect buffers) +@end ifnotinfo +will contain the entire buffer, but will be narrowed to the current +tree. Editing the indirect buffer will also change the original buffer, +but without affecting visibility in that buffer.}. With numerical +prefix ARG, go up to this level and then take that tree. If ARG is +negative, go up that many levels. With @kbd{C-u} prefix, do not remove +the previously used indirect buffer. @end table When Emacs first visits an Org-mode file, the global state is set to @@ -2564,9 +2570,11 @@ useful if more than two TODO states are possible (@pxref{TODO extensions}). @item C-c C-v View TODO items in a @emph{sparse tree} (@pxref{Sparse trees}). Folds the entire buffer, but shows all TODO items and the headings hierarchy -above them. With prefix arg, show also the DONE entries. With -numerical prefix N, show the tree for the Nth keyword in the variable -@code{org-todo-keywords}. +above them. With prefix arg, search for a specific TODO. You will be +prompted for the keyword, and you can also give a list of keywords like +@code{kwd1|kwd2|...}. With numerical prefix N, show the tree for the +Nth keyword in the variable @code{org-todo-keywords}. With two prefix +args, find all TODO and DONE entries. @kindex C-c a t @item C-c a t Show the global TODO list. This collects the TODO items from all @@ -2584,10 +2592,9 @@ the TODO entries directly from that buffer (@pxref{Agenda commands}). @cindex extended TODO keywords The default implementation of TODO entries is just two states: TODO and -DONE. You can, however, use the TODO feature for more complicated -things by configuring the variables @code{org-todo-keywords} and -@code{org-todo-interpretation}. Using special setup, you can even use -TODO keywords in different ways in different org files. +DONE. You can use the TODO feature for more complicated things by +configuring the variable @code{org-todo-keywords}. With special setup, +the TODO keyword system can work differently in different files. Note that @i{tags} are another way to classify headlines in general and TODO items in particular (@pxref{Tags}). @@ -2595,8 +2602,8 @@ TODO items in particular (@pxref{Tags}). @menu * Workflow states:: From TODO to DONE in steps * TODO types:: I do this, Fred the rest -* Per file keywords:: Different files, different requirements * Multiple sets in one file:: Mixing it all, and still finding your way +* Per file keywords:: Different files, different requirements @end menu @node Workflow states, TODO types, TODO extensions, TODO extensions @@ -2604,78 +2611,134 @@ TODO items in particular (@pxref{Tags}). @cindex TODO workflow @cindex workflow states as TODO keywords -You can use TODO keywords to indicate different states in the process -of working on an item, for example: +You can use TODO keywords to indicate different @emph{sequential} states +in the process of working on an item, for example@footnote{Changing +this variable only becomes effective after restarting Org-mode in a +buffer.}: @lisp -(setq org-todo-keywords '("TODO" "FEEDBACK" "VERIFY" "DONE") - org-todo-interpretation 'sequence) +(setq org-todo-keywords + '((sequence "TODO" "FEEDBACK" "VERIFY" "|" "DONE" "DELEGATED"))) @end lisp +The vertical bar separates the TODO keywords (states that @emph{need +action}) from the DONE states (which need @emph{no further action}. If +you don't provide the separator bar, the last state is used as the DONE +state. @cindex completion, of TODO keywords -Changing these variables only becomes effective in a new Emacs session. -With this setup, the command @kbd{C-c C-t} will cycle an entry from -TODO to FEEDBACK, then to VERIFY, and finally to DONE. You may also -use a prefix argument to quickly select a specific state. For example -@kbd{C-3 C-c C-t} will change the state immediately to VERIFY. +With this setup, the command @kbd{C-c C-t} will cycle an entry from TODO +to FEEDBACK, then to VERIFY, and finally to DONE and DELEGATED. You may +also use a prefix argument to quickly select a specific state. For +example @kbd{C-3 C-c C-t} will change the state immediately to VERIFY. If you define many keywords, you can use in-buffer completion (see -@ref{Completion}) to insert these words into the buffer. Changing a todo -state can be logged with a timestamp, see @ref{Tracking TODO state +@ref{Completion}) to insert these words into the buffer. Changing a +todo state can be logged with a timestamp, see @ref{Tracking TODO state changes} for more information. -@node TODO types, Per file keywords, Workflow states, TODO extensions +@node TODO types, Multiple sets in one file, Workflow states, TODO extensions @subsection TODO keywords as types @cindex TODO types @cindex names as TODO keywords @cindex types as TODO keywords The second possibility is to use TODO keywords to indicate different -types of action items. For example, you might want to indicate that -items are for ``work'' or ``home''. If you are into David Allen's -@emph{Getting Things DONE}, you might want to use todo types -@samp{NEXTACTION}, @samp{WAITING}, @samp{MAYBE}. Or, when you work -with several people on a single project, you might want to assign -action items directly to persons, by using their names as TODO -keywords. This would be set up like this: +@emph{types} of action items. For example, you might want to indicate +that items are for ``work'' or ``home''. Or, when you work with several +people on a single project, you might want to assign action items +directly to persons, by using their names as TODO keywords. This would +be set up like this: @lisp -(setq org-todo-keywords '("Fred" "Sara" "Lucy" "Mike" "DONE") - org-todo-interpretation 'type) +(setq org-todo-keywords '((type "Fred" "Sara" "Lucy" "|" "DONE"))) @end lisp -In this case, different keywords do not indicate a sequence, but -rather different types. So it is normally not useful to change from -one type to another. Therefore, in this case the behavior of the -command @kbd{C-c C-t} is changed slightly@footnote{This is also true -for the @kbd{t} command in the timeline and agenda buffers.}. When -used several times in succession, it will still cycle through all -names. But when you return to the item after some time and execute -@kbd{C-c C-t} again, it will switch from each name directly to DONE. -Use prefix arguments or completion to quickly select a specific name. -You can also review the items of a specific TODO type in a sparse tree -by using a numeric prefix to @kbd{C-c C-v}. For example, to see all -things Lucy has to do, you would use @kbd{C-3 C-c C-v}. To collect -Lucy's items from all agenda files into a single buffer, you -would use the prefix arg as well when creating the global todo list: -@kbd{C-3 C-c t}. +In this case, different keywords do not indicate a sequence, but rather +different types. So the normal work flow would be to assign a task to a +person, and later to mark it DONE. Org-mode supports this style by +adapting the workings of the command @kbd{C-c C-t}@footnote{This is also +true for the @kbd{t} command in the timeline and agenda buffers.}. When +used several times in succession, it will still cycle through all names, +in order to first select the right type for a task. But when you return +to the item after some time and execute @kbd{C-c C-t} again, it will +switch from any name directly to DONE. Use prefix arguments or +completion to quickly select a specific name. You can also review the +items of a specific TODO type in a sparse tree by using a numeric prefix +to @kbd{C-c C-v}. For example, to see all things Lucy has to do, you +would use @kbd{C-3 C-c C-v}. To collect Lucy's items from all agenda +files into a single buffer, you would use the prefix arg as well when +creating the global todo list: @kbd{C-3 C-c t}. -@node Per file keywords, Multiple sets in one file, TODO types, TODO extensions -@subsection Setting up TODO keywords for individual files +@node Multiple sets in one file, Per file keywords, TODO types, TODO extensions +@subsection Multiple keyword sets in one file +@cindex todo keyword sets + +Sometimes you may want to use different sets of TODO keywords in +parallel. For example, you may want to have the basic +@code{TODO}/@code{DONE}, but also a workflow for bug fixing, and a +separate state indicating that an item has been canceled (so it is not +DONE, but also does not require action). Your setup would then look +like this: + +@lisp +(setq org-todo-keywords + '((sequence "TODO" "|" "DONE") + (sequence "REPORT" "BUG" "KNOWNCAUSE" "|" "FIXED") + (sequence "|" "CANCELED"))) +@end lisp + +The keywords should all be different, this helps Org-mode to keep track +of which subsequence should be used for a given entry. In this setup, +@kbd{C-c C-t} only operates within a subsequence, so it switches from +@code{DONE} to (nothing) to @code{TODO}, and from @code{FIXED} to +(nothing) to @code{REPORT}. Therefore you need a mechanism to initially +select the correct sequence. Besides the obvious ways like typing a +keyword or using completion, you may also apply the following commands: + +@table @kbd +@kindex C-S-@key{right} +@kindex C-S-@key{left} +@item C-S-@key{right} +@itemx C-S-@key{left} +These keys jump from one TODO subset to the next. In the above example, +@kbd{C-S-@key{right}} would jump from @code{TODO} or @code{DONE} to +@code{REPORT}, and any of the words in the second row to @code{CANCELED}. +@kindex S-@key{right} +@kindex S-@key{left} +@item S-@key{right} +@itemx S-@key{left} +@kbd{S-@key{}} and @kbd{S-@key{}} and walk through +@emph{all} keywords from all sets, so for example @kbd{S-@key{}} +would switch from @code{DONE} to @code{REPORT} in the example above. +@end table + +@node Per file keywords, , Multiple sets in one file, TODO extensions +@subsection Setting up keywords for individual files @cindex keyword options @cindex per file keywords -It can be very useful to use different aspects of the TODO mechanism -in different files, which is not possible with the global settings -described above. For file-local settings, you need to add special -lines to the file which set the keywords and interpretation for that -file only. For example, to set one of the two examples discussed -above, you need one of the following lines, starting in column zero -anywhere in the file: +It can be very useful to use different aspects of the TODO mechanism in +different files. For file-local settings, you need to add special lines +to the file which set the keywords and interpretation for that file +only. For example, to set one of the two examples discussed above, you +need one of the following lines, starting in column zero anywhere in the +file: @example -#+SEQ_TODO: TODO FEEDBACK VERIFY DONE -#+TYP_TODO: Fred Sara Lucy Mike DONE +#+SEQ_TODO: TODO FEEDBACK VERIFY | DONE CANCELED @end example +or +@example +#+TYP_TODO: Fred Sara Lucy Mike | DONE +@end example + +A setup for using several sets in parallel would be: + +@example +#+SEQ_TODO: "TODO" "|" "DONE" +#+SEQ_TODO: "REPORT" "BUG" "KNOWNCAUSE" "|" "FIXED" +#+SEQ_TODO: "|" "CANCELED" +@end example + @cindex completion, of option keywords @kindex M-@key{TAB} @@ -2683,53 +2746,15 @@ anywhere in the file: @samp{#+} into the buffer and then use @kbd{M-@key{TAB}} completion. @cindex DONE, final TODO keyword -Remember that the last keyword must always mean that the item is DONE -(although you may use a different word). After changing one of these -lines, use @kbd{C-c C-c} with the cursor still in the line to make the -changes known to Org-mode@footnote{Org-mode parses these lines only when +Remember that the keywords after the vertical bar (or the last keyword +if no bar is there) must always mean that the item is DONE (although you +may use a different word). After changing one of these lines, use +@kbd{C-c C-c} with the cursor still in the line to make the changes +known to Org-mode@footnote{Org-mode parses these lines only when Org-mode is activated after visiting a file. @kbd{C-c C-c} with the cursor in a line starting with @samp{#+} is simply restarting Org-mode for the current buffer.}. -@node Multiple sets in one file, , Per file keywords, TODO extensions -@subsection Multiple TODO keyword sets in one file -@cindex todo keyword sets - -Sometimes you may want to use different sets of TODO keywords in the -same file. For example, you may want to have the basic -@code{TODO}/@code{DONE}, but also a workflow for bug fixing. Your setup -would then look like this: - -@example -#+SEQ_TODO: TODO DONE -#+SEQ_TODO: REPORT BUG KNOWNCAUSE RESOLVED -@end example - -The keywords should all be different, this helps Org-mode to keep track -of which subsequence should be used for a given entry. In this setup, -@kbd{C-c C-t} only operates within a subsequence, so it switches from -@code{DONE} to (nothing) to @code{TODO}, and from @code{RESOLVED} to -(nothing) to @code{REPORT}. Therefore you need a mechanism to initially -select the correct sequence. Besides the obvious ways like typing a -keyword or using completion, you may also apply the following commands: - -@table @kbd -@kindex S-@key{right} -@kindex S-@key{left} -@item S-@key{right} -@itemx S-@key{left} -@kbd{S-@key{}} and @kbd{S-@key{}} and walk through all -keywords from all sets, so for example @kbd{S-@key{}} would -switch from @code{DONE} to @code{REPORT} in the example above. -@kindex C-S-@key{right} -@kindex C-S-@key{left} -@item C-S-@key{right} -@itemx C-S-@key{left} -These key jump from one TODO subset to the next. So -@kbd{C-S-@key{right}} would jump from @code{TODO} to @code{REPORT} and -from @code{KNOWNCAUSE} to @code{TODO} in the above example. -@end table - @node Priorities, Breaking down tasks, TODO extensions, TODO items @section Priorities @cindex priorities @@ -3847,10 +3872,12 @@ the TODO entries directly from that buffer (@pxref{Agenda commands}). @kindex C-c a T @item C-c a T @cindex TODO keyword matching -Like the above, but allows selection of a specific TODO keyword. You can -also do this by specifying a prefix argument to @kbd{C-c a t}. With a -@kbd{C-u} prefix you are prompted for a keyword. With a numeric -prefix, the Nth keyword in @code{org-todo-keywords} is selected. +Like the above, but allows selection of a specific TODO keyword. You +can also do this by specifying a prefix argument to @kbd{C-c a t}. With +a @kbd{C-u} prefix you are prompted for a keyword, and you may also +specify several keywords by separating them with @samp{|} as boolean OR +operator. With a numeric prefix, the Nth keyword in +@code{org-todo-keywords} is selected. @kindex r The @kbd{r} key in the agenda buffer regenerates it, and you can give a prefix argument to this command to change the selected TODO keyword, @@ -4879,10 +4906,15 @@ Export as HTML file @file{myfile.html}. @kindex C-c C-e b @item C-c C-e b Export as HTML file and open it with a browser. +@kindex C-c C-e H +@item C-c C-e H +Export to a temporary buffer, do not create a file. @kindex C-c C-e v h @kindex C-c C-e v b +@kindex C-c C-e v H @item C-c C-e v h @item C-c C-e v b +@item C-c C-e v H Export only the visible part of the document. @end table @@ -5085,11 +5117,11 @@ Toggle the COMMENT keyword at the beginning of an entry. @subsection Text before the first headline Org-mode normally ignores any text before the first headline when -exporting, because this region is often used for internal links to speed -up navigation etc. However, there are occasions when you might want to -have some text before the first headline, like a small intorduction, -special HTML code with a navigation bar, etc. You can ask to have this -part of the file exported as well by setting the variable +exporting, leaving this region for internal links to speed up navigation +etc. However, in publishing-oriented files, you might want to have some +text before the first headline, like a small introduction, special HTML +code with a navigation bar, etc. You can ask to have this part of the +file exported as well by setting the variable @code{org-export-skip-text-before-1st-heading} to @code{nil}. On a per-file basis, you can get the same effect with @@ -5098,12 +5130,13 @@ per-file basis, you can get the same effect with @end example The text before the first headline will be fully processed -(@pxref{Enhancing text}). If you need to include literal HTML, use the -special constructs described in @ref{Quoting HTML tags}. The table of -contents is normally inserted directly before the first headline of the -file. If you would like to get it to a different location, insert -the string @code{[TABLE-OF-CONTENTS]} on a line by itself at the desired -location. +(@pxref{Enhancing text}), and the first non-comment line becomes the +title of the exported document. If you need to include literal HTML, +use the special constructs described in @ref{Quoting HTML tags}. The +table of contents is normally inserted directly before the first +headline of the file. If you would like to get it to a different +location, insert the string @code{[TABLE-OF-CONTENTS]} on a line by +itself at the desired location. Finally, if you want to use the space before the first headline for internal purposes, but @emph{still} want to place something before the @@ -5142,7 +5175,9 @@ backend supports lists. See @xref{Plain lists}. @cindex italic text @item You can make words @b{*bold*}, @i{/italic/}, _underlined_, -@code{=code=}, and @samp{+strikethrough+}. +@code{=code=}, and even @samp{+strikethrough+}@footnote{but remember +that strikethrough is typographically evil and should @i{never} be +used.}. @cindex horizontal rules, in exported files @item @@ -5950,10 +5985,12 @@ rather use @kbd{C-c .} to re-insert the timestamp. @item @kbd{S-@key{RET}} @tab @kbd{C-c C-x c} @tab @item @kbd{M-@key{RET}} @tab @kbd{C-c C-x m} @tab @kbd{@key{Esc} @key{RET}} @item @kbd{M-S-@key{RET}} @tab @kbd{C-c C-x M} @tab -@item @kbd{S-@key{left}} @tab @kbd{C-c C-x @key{left}} @tab -@item @kbd{S-@key{right}} @tab @kbd{C-c C-x @key{right}} @tab -@item @kbd{S-@key{up}} @tab @kbd{C-c C-x @key{up}} @tab -@item @kbd{S-@key{down}} @tab @kbd{C-c C-x @key{down}} @tab +@item @kbd{S-@key{left}} @tab @kbd{C-c @key{left}} @tab +@item @kbd{S-@key{right}} @tab @kbd{C-c @key{right}} @tab +@item @kbd{S-@key{up}} @tab @kbd{C-c @key{up}} @tab +@item @kbd{S-@key{down}} @tab @kbd{C-c @key{down}} @tab +@item @kbd{C-S-@key{left}} @tab @kbd{C-c C-x @key{left}} @tab +@item @kbd{C-S-@key{right}} @tab @kbd{C-c C-x @key{right}} @tab @end multitable @node Interaction, Bugs, TTY keys, Miscellaneous diff --git a/orgcard.pdf b/orgcard.pdf index cb8f25b1a..571001757 100644 Binary files a/orgcard.pdf and b/orgcard.pdf differ diff --git a/orgcard.tex b/orgcard.tex index c63364aad..e4c18b8c8 100644 --- a/orgcard.tex +++ b/orgcard.tex @@ -1,5 +1,5 @@ % Reference Card for Org Mode -\def\orgversionnumber{4.69} +\def\orgversionnumber{4.70} \def\versionyear{2007} % latest update \def\year{2007} % latest copyright year % @@ -512,6 +512,8 @@ after ``{\tt :}'', and dictionary words elsewhere. \section{TODO Items and Checkboxes} \key{rotate the state of the current item}{C-c C-t} +\metax{select next/previous state}{S-LEFT/RIGHT} +\metax{select next/previous set}{C-S-LEFT/RIGHT} \key{view TODO items in a sparse tree}{C-c C-v} \key{view 3rd TODO keyword's sparse tree}{C-3 C-c C-v} @@ -558,8 +560,7 @@ after ``{\tt :}'', and dictionary words elsewhere. %\key{... forward/backward one month}{M-S-LEFT/RIGT} \key{Toggle custom format display for dates/times}{C-c C-x C-t} - -\section{Clocking Time} +{\bf Clocking time} \key{start clock on current item}{C-c C-x C-i} \key{stop clock on current item}{C-c C-x C-o}