diff --git a/ChangeLog b/ChangeLog index ac19838e5..5840b127e 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,24 @@ +2007-12-17 Carsten Dominik + + * org.el (org-first-list-item-p): New function. + (org-last-remember-storage-locations): New variable. + (org-get-refile-targets): Interpret the new maxlevel setting. + (org-refile-targets): New option `:maxlevel'. + +2007-12-14 Carsten Dominik + + * org.el (org-copy-subtree): Include empty lines before but not + after subtree. + (org-back-over-empty-lines, org-skip-whitespace): New functions. + (org-move-item-down, org-move-item-up): Include empty lines before + but not after item. + (org-first-sibling-p): New function. + +2007-12-13 Carsten Dominik + + * org.el (org-remember-apply-template): Defaults, completions and + history for template prompts. Also, interpret new `%!' escape. + 2007-12-03 Carsten Dominik * org.el (org-context-choices): New constant. diff --git a/Makefile b/Makefile index 2f44a11e5..8b4a5bf76 100644 --- a/Makefile +++ b/Makefile @@ -202,12 +202,12 @@ release: cp RELEASEDIR/org-$(TAG).tar.gz RELEASEDIR/org.tar.gz (cd $(HG_RELEASES); rm -rf $(DISTFILES) xemacs) cp -r org-$(TAG)/* $(HG_RELEASES) - (cd $(HG_RELEASES); hg addremove; hg ci -m $(TAG); hg tag -f $(TAG)) + (cd $(HG_RELEASES); hg addremove; hg ci -m $(TAG); hg tag $(TAG)) trackrelease: (cd $(HG_RELEASES); rm -rf $(DISTFILES) xemacs) cp -r org-$(TAG)/* $(HG_RELEASES) - (cd $(HG_RELEASES); hg addremove; hg ci -m $(TAG); hg tag -f $(TAG)) + (cd $(HG_RELEASES); hg addremove; hg ci -m $(TAG); hg tag $(TAG)) upload: (cd RELEASEDIR; lftp -f ../ftp_script) diff --git a/org b/org index 2989fedf3..27ca1aafd 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 5.16a). + This manual is for Org-mode (version 5.17). 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 5.16a). +This manual is for Org-mode (version 5.17). Copyright (C) 2004, 2005, 2006, 2007 Free Software Foundation @@ -61,7 +61,7 @@ This manual is for Org-mode (version 5.16a). * Miscellaneous:: All the rest which did not fit elsewhere * Extensions and Hacking:: It is possible to write add-on code * History and Acknowledgments:: How Org-mode came into being -* Main Index:: +* Index:: The index * Key Index:: Key bindings and where they are described --- The Detailed Node Listing --- @@ -138,10 +138,10 @@ TODO items Extended use of TODO keywords * Workflow states:: From TODO to DONE in steps -* TODO types:: I do this, Fred the rest +* TODO types:: I do this, Fred does the rest * Multiple sets in one file:: Mixing it all, and still finding your way * Fast access to TODO states:: Single letter selection of a state -* Per file keywords:: Different files, different requirements +* Per-file keywords:: Different files, different requirements * Faces for TODO keywords:: Highlighting states Progress Logging @@ -526,24 +526,23 @@ File: org, Node: Conventions, Prev: Feedback, Up: Introduction 1.5 Typesetting conventions used in this manual =============================================== -Org-mode has 3 types of keywords that are being used. TODO keywords, -tags, and property names. For this manual we are using the following -conventions: +Org-mode uses three types of keywords: TODO keywords, tags, and property +names. In this manual we use the following conventions: `TODO' `WAITING' - TODO keyword are written with all capitals, even if they are + TODO keywords are written with all capitals, even if they are user-defined. `boss' `ARCHIVE' - User-defined Tags are written in lowercase, built-in tags with - special meaning a all-caps. + User-defined tags are written in lowercase; built-in tags with + special meaning are written with all capitals. `Release' `PRIORITY' - User-defined properties are capitalized in all examples, while - built-in properties with special meaning are all-caps. + User-defined properties are capitalized; built-in properties with + special meaning are written with all capitals.  File: org, Node: Document structure, Next: Tables, Prev: Introduction, Up: Top @@ -655,9 +654,11 @@ the visibility in the buffer. `C-c C-r' Reveal context around point, showing the current entry, the following heading and the hierarchy above. Useful for working - near a location exposed by a sparse tree command (*note Sparse - trees::) or an agenda command (*note Agenda commands::). With - prefix arg show, on each level, all sibling headings. + near a location that has been exposed by a sparse tree command + (*note Sparse trees::) or an agenda command (*note Agenda + commands::). With prefix arg show, on each + + level, all sibling headings. `C-c C-x b' Show the current subtree in an indirect buffer(3). With numerical @@ -915,10 +916,10 @@ File: org, Node: Sparse trees, Next: Plain lists, Prev: Archiving, Up: Docum ================ An important feature of Org-mode is the ability to construct _sparse -trees_ for selected information in an outline tree. A sparse tree -means that the entire document is folded as much as possible, but the -selected information is made visible along with the headline structure -above it(1). Just try it out and you will see immediately how it works. +trees_ for selected information in an outline tree, so that the entire +document is folded as much as possible, but the selected information is +made visible along with the headline structure above it(1). Just try +it out and you will see immediately how it works. Org-mode contains several commands creating such trees, all these commands can be accessed through a dispatcher: @@ -938,7 +939,8 @@ commands can be accessed through a dispatcher: by an editing command, or by pressing `C-c C-c'. When called with a `C-u' prefix argument, previous highlights are kept, so several calls to this command can be stacked. - For frequently used sparse trees of specific search strings, you can + +For frequently used sparse trees of specific search strings, you can use the variable `org-agenda-custom-commands' to define fast keyboard access to specific sparse trees. These commands will then be accessible through the agenda dispatcher (*note Agenda dispatcher::). @@ -977,11 +979,12 @@ File: org, Node: Plain lists, Next: Drawers, Prev: Sparse trees, Up: Documen Within an entry of the outline tree, hand-formatted lists can provide additional structure. They also provide a way to create lists of checkboxes (*note Checkboxes::). Org-mode supports editing such lists, -and the HTML exporter (*note Exporting::) does parse and format them. +and the HTML exporter (*note Exporting::) parses and formats them. Org-mode knows ordered and unordered lists. Unordered list items start with `-', `+', or `*'(1) as bullets. Ordered list items start -with `1.' or `1)'. Items belonging to the same list must have the same +with a numeral followed by either a period or a right parenthesis, such +as `1.' or `1)'. Items belonging to the same list must have the same indentation on the first line. In particular, if an ordered list reaches number `10.', then the 2-digit numbers must be written left-aligned with the other numbers in the list. Indentation also @@ -1053,8 +1056,8 @@ line of an item (the line with the bullet or number). `C-c C-c' If there is a checkbox (*note Checkboxes::) in the item line, - toggle the state of the checkbox. If not, make this command makes - sure that all the items on this list level use the same bullet. + toggle the state of the checkbox. If not, this command makes sure + that all the items on this list level use the same bullet. Furthermore, if this is an ordered list, make sure the numbering is ok. @@ -1069,7 +1072,7 @@ line of an item (the line with the bullet or number). be seen as top-level headlines. Also, when you are hiding leading stars to get a clean outline view, plain list items starting with a star are visually indistinguishable from true headlines. In short: -even though `*' is supported, it may be better not to use it for plain +even though `*' is supported, it may be better to not use it for plain list items. (2) Org-mode only changes the filling settings for Emacs. For @@ -1084,8 +1087,8 @@ File: org, Node: Drawers, Next: orgstruct-mode, Prev: Plain lists, Up: Docum Sometimes you want to keep information associated with an entry, but you normally don't want to see it. For this, Org-mode has _drawers_. -Drawers need to be configured with the variable `org-drawers'(1), and -look like this: +Drawers need to be configured with the variable `org-drawers'(1). +Drawers look like this: ** This is a headline Still outside the drawer @@ -1103,7 +1106,7 @@ properties (*note Properties and columns::). ---------- Footnotes ---------- (1) You can define drawers on a per-file basis with a line like -`#+DRAWERS: HIDDEN PROPPERTIES STATE' +`#+DRAWERS: HIDDEN PROPERTIES STATE'  File: org, Node: orgstruct-mode, Prev: Drawers, Up: Document structure @@ -1133,9 +1136,9 @@ File: org, Node: Tables, Next: Hyperlinks, Prev: Document structure, Up: Top 3 Tables ******** -Org-mode has a very fast and intuitive table editor built-in. -Spreadsheet-like calculations are supported in connection with the -Emacs `calc' package. +Org-mode comes with a fast and intuitive table editor. Spreadsheet-like +calculations are supported in connection with the Emacs `calc' package +(*note Calc: (calc)Calc.). * Menu: @@ -1956,8 +1959,8 @@ File: org, Node: Hyperlinks, Next: TODO items, Prev: Tables, Up: Top 4 Hyperlinks ************ -Just like HTML, Org-mode provides links inside a file, and external -links to other files, Usenet articles, emails, and much more. +Like HTML, Org-mode provides links inside a file, external links to +other files, Usenet articles, emails, and much more. * Menu: @@ -2360,16 +2363,16 @@ File: org, Node: TODO items, Next: Tags, Prev: Hyperlinks, Up: Top 5 TODO items ************ -Org-mode does not maintain TODO lists as a separate document. TODO -items are an integral part of the notes file, because TODO items -usually come up while taking notes! With Org-mode, you simply mark any -entry in a tree as being a TODO item. In this way, the information is -not duplicated, and the entire context from which the item emerged is -always present when you check. +Org-mode does not maintain TODO lists as separate documents. Instead, +TODO items are an integral part of the notes file, because TODO items +usually come up while taking notes! With Org-mode, simply mark any +entry in a tree as being a TODO item. In this way, information is not +duplicated, and the entire context from which the TODO item emerged is +always present. - Of course, this technique causes TODO items to be scattered -throughout your file. Org-mode provides methods to give you an -overview over all things you have to do. + Of course, this technique for managing TODO items scatters them +throughout your notes file. Org-mode compensates for this by providing +methods to give you an overview of all the things that you have to do. * Menu: @@ -2386,7 +2389,7 @@ File: org, Node: TODO basics, Next: TODO extensions, Prev: TODO items, Up: T 5.1 Basic TODO functionality ============================ -Any headline can become a TODO item by starting it with the word TODO, +Any headline becomes a TODO item when it starts with the word `TODO', for example: *** TODO Write letter to Sam Fortune @@ -2403,21 +2406,20 @@ The most important commands to work with TODO entries are: agenda buffers with the `t' command key (*note Agenda commands::). `C-u C-c C-t' - Select a specific keyword using completion of (if it has been set + Select a specific keyword using completion or (if it has been set up) the fast selection interface. `S-' `S-' Select the following/preceding TODO state, similar to cycling. - Mostly useful if more than two TODO states are possible (*note + Useful mostly if more than two TODO states are possible (*note TODO extensions::). `C-c C-c' - Use the fast tag interface to quickly and directly select a - specific TODO state. For this you need to assign keys to TODO - state, like this: + Use the fast tag interface to directly select a specific TODO + state. For this you need to assign keys to TODO states, like this: #+SEQ_TODO: TODO(t) STARTED(s) WAITING(w) | DONE(d) - See *Note Per file keywords:: and *Note Setting tags:: for more + See *Note Per-file keywords:: and *Note Setting tags:: for more information. `C-c C-v' @@ -2432,12 +2434,11 @@ The most important commands to work with TODO entries are: entries. `C-c a t' - Show the global TODO list. This collects the TODO items from all - agenda files (*note Agenda views::) into a single buffer. The - buffer is in `agenda-mode', so there are commands to examine and - manipulate the TODO entries directly from that buffer (*note - Agenda commands::). *Note Global TODO list::, for more - information. + Show the global TODO list. Collects the TODO items from all agenda + files (*note Agenda views::) into a single buffer. The new buffer + will be in `agenda-mode', which provides commands to examine and + manipulate the TODO entries from the new buffer (*note Agenda + commands::). *Note Global TODO list::, for more information. `S-M-' Insert a new TODO entry below the current one. @@ -2448,10 +2449,10 @@ File: org, Node: TODO extensions, Next: Progress logging, Prev: TODO basics, 5.2 Extended use of TODO keywords ================================= -The default implementation of TODO entries is just two states: TODO and -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. +By default, marked TODO entries have one of only two states: TODO and +DONE. Org-mode allows you to classify TODO items in more complex ways +with _TODO keywords_ (stored in `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::). @@ -2459,10 +2460,10 @@ TODO items in particular (*note Tags::). * Menu: * Workflow states:: From TODO to DONE in steps -* TODO types:: I do this, Fred the rest +* TODO types:: I do this, Fred does the rest * Multiple sets in one file:: Mixing it all, and still finding your way * Fast access to TODO states:: Single letter selection of a state -* Per file keywords:: Different files, different requirements +* Per-file keywords:: Different files, different requirements * Faces for TODO keywords:: Highlighting states  @@ -2567,7 +2568,7 @@ using completion, you may also apply the following commands: `DONE' to `REPORT' in the example above.  -File: org, Node: Fast access to TODO states, Next: Per file keywords, Prev: Multiple sets in one file, Up: TODO extensions +File: org, Node: Fast access to TODO states, Next: Per-file keywords, Prev: Multiple sets in one file, Up: TODO extensions 5.2.4 Fast access to TODO states -------------------------------- @@ -2592,7 +2593,7 @@ default. Check also the variable state through the tags interface (*note Setting tags::).  -File: org, Node: Per file keywords, Next: Faces for TODO keywords, Prev: Fast access to TODO states, Up: TODO extensions +File: org, Node: Per-file keywords, Next: Faces for TODO keywords, Prev: Fast access to TODO states, Up: TODO extensions 5.2.5 Setting up keywords for individual files ---------------------------------------------- @@ -2630,7 +2631,7 @@ 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: Faces for TODO keywords, Prev: Per file keywords, Up: TODO extensions +File: org, Node: Faces for TODO keywords, Prev: Per-file keywords, Up: TODO extensions 5.2.6 Faces for TODO keywords ----------------------------- @@ -2733,17 +2734,20 @@ File: org, Node: Priorities, Next: Breaking down tasks, Prev: Progress loggin 5.4 Priorities ============== -If you use Org-mode extensively to organize your work, you may end up -with a number of TODO entries so large that you'd like to prioritize -them. This can be done by placing a _priority cookie_ into the -headline, like this +If you use Org-mode extensively, you may end up enough TODO items that +it starts to make sense to prioritize them. Prioritizing can be done by +placing a _priority cookie_ into the headline of a TODO item, like this *** TODO [#A] Write letter to Sam Fortune -With its standard setup, Org-mode supports priorities `A', `B', and -`C'. `A' is the highest priority. An entry without a cookie is -treated as priority `B'. Priorities make a difference only in the -agenda (*note Weekly/Daily agenda::). +By default, Org-mode supports three priorities: `A', `B', and `C'. `A' +is the highest priority. An entry without a cookie is treated as +priority `B'. Priorities make a difference only in the agenda (*note +Weekly/Daily agenda::); outside the agenda, they have no inherent +meaning to Org-mode. + + Priorities can be attached to any outline tree entries; they do not +need to be TODO items. `C-c ,' Set the priority of the current headline. The command prompts for @@ -2794,13 +2798,15 @@ File: org, Node: Checkboxes, Prev: Breaking down tasks, Up: TODO items 5.6 Checkboxes ============== -Every item in a plain list (*note Plain lists::) can be made a checkbox -by starting it with the string `[ ]'. This feature is similar to TODO -items (*note TODO items::), but more lightweight. Checkboxes are not -included into the global TODO list, so they are often great to split a -task into a number of simple steps. Or you can use them in a shopping -list. To toggle a checkbox, use `C-c C-c', or try Piotr Zielinski's -`org-mouse.el'. Here is an example of a checkbox list. +Every item in a plain list (*note Plain lists::) can be made into a +checkbox by starting it with the string `[ ]'. This feature is similar +to TODO items (*note TODO items::), but is more lightweight. +Checkboxes are not included into the global TODO list, so they are often +great to split a task into a number of simple steps. Or you can use +them in a shopping list. To toggle a checkbox, use `C-c C-c', or use +the mouse (thanks to Piotr Zielinski's `org-mouse.el'). + + Here is an example of a checkbox list. * TODO Organize party [3/6] - call people [1/3] @@ -2812,16 +2818,17 @@ list. To toggle a checkbox, use `C-c C-c', or try Piotr Zielinski's - [X] talk to the neighbors The `[3/6]' and `[1/3]' in the first and second line are cookies -indicating how many checkboxes are present in this entry, and how many -of them have been checked off. This can give you an idea on how many -checkboxes remain, even without opening a folded entry. The cookies -can be placed into a headline or into (the first line of) a plain list -item. Each cookie covers all checkboxes structurally below that -headline/item. You have to insert the cookie yourself by typing either -`[/]' or `[%]'. In the first case you get an `n out of m' result, in -the second case you get information about the percentage of checkboxes -checked (in the above example, this would be `[50%]' and `[33%], -respectively'). +indicating how many checkboxes present in this entry have been checked +off, and the total number of checkboxes are present. This can give you +an idea on how many checkboxes remain, even without opening a folded +entry. The cookies can be placed into a headline or into (the first +line of) a plain list item. Each cookie covers all checkboxes +structurally below the headline/item on which the cookie appear. You +have to insert the cookie yourself by typing either `[/]' or `[%]'. +With `[/]' you get an `n out of m' result, as in the examples above. +With `[%]' you get information about the percentage of checkboxes +checked (in the above example, this would be `[50%]' and `[33%]', +respectively). The following commands work with checkboxes: @@ -2862,14 +2869,14 @@ File: org, Node: Tags, Next: Properties and columns, Prev: TODO items, Up: T 6 Tags ****** -If you wish to implement a system of labels and contexts for -cross-correlating information, an excellent way is to assign tags to -headlines. Org-mode has extensive support for using tags. +An excellent way to implement labels and contexts for cross-correlating +information is to assign tags to headlines. Org-mode has extensive +support for tags. - Every headline can contain a list of tags, at the end of the -headline. Tags are normal words containing letters, numbers, `_', and -`@'. Tags must be preceded and followed by a single colon; like -`:WORK:'. Several tags can be specified like `:work:URGENT:'. + Every headline can contain a list of tags; they occur at the end of +the headline. Tags are normal words containing letters, numbers, `_', +and `@'. Tags must be preceded and followed by a single colon, e.g., +`:WORK:'. Several tags can be specified, as in `:work:URGENT:'. * Menu: @@ -2892,12 +2899,14 @@ well. For example, in the list *** TODO Prepare slides for him :action: the final heading will have the tags `:work:', `:boss:', `:notes:', and -`:action:'. When executing tag searches and Org-mode finds that a +`:action:' even though the final heading is not explicitly marked with +those tags. When executing tag searches and Org-mode finds that a certain headline matches the search criterion, it will not check any -sublevel headline, assuming that these likely also match, and that the -list of matches can become very long. This may not be what you want, -however, and you can influence inheritance and searching using the -variables `org-use-tag-inheritance' and `org-tags-match-list-sublevels'. +sublevel headline, assuming that these also match and that the list of +matches could become very long because of that. If you do want the +subevels be tested and listed as well, you may set the variable +`org-tags-match-list-sublevels'. To turn off tag inheritance entirely, +use the variable `org-use-tag-inheritance'.  File: org, Node: Setting tags, Next: Tag searches, Prev: Tag inheritance, Up: Tags @@ -2930,7 +2939,7 @@ default tags for a given file with lines like If you have globally defined your preferred set of tags using the variable `org-tag-alist', but would like to use a dynamic tag list in a -specific file: Just add an empty TAGS option line to that file: +specific file, add an empty TAGS option line to that file: #+TAGS: @@ -3028,7 +3037,7 @@ File: org, Node: Tag searches, Prev: Setting tags, Up: Tags 6.3 Tag searches ================ -Once a tags system has been set up, it can be used to collect related +Once a system of tags has been set up, it can be used to collect related information into special lists. `C-c \' @@ -3105,7 +3114,21 @@ File: org, Node: Properties and columns, Next: Dates and times, Prev: Tags, Properties are a set of key-value pairs associated with an entry. There are two main applications for properties in Org-mode. First, properties -are like tags, but with a value. For example, in a file where you +are like tags, but with a value. Second, you can use properties to +implement (very basic) database capabilities in an Org-mode buffer. For +an example of the first application, imagine maintaining a file where +you document bugs and plan releases of a piece of software. Instead of +using tags like `:release_1:', `:release_2:', one can use a property, +say `Release', that in different subtrees has different values, such as +`1.0' or `2.0'. For an example of the second application of +properties, imagine keeping track of one's music CD's, where properties +could be things such as the album artist, date of release, number of +tracks, and so on. + + Properties can be conveiently edited and viewed in column view +(*note Column view::). + + are like tags, but with a value. For example, in a file where you document bugs and plan releases of a piece of software, instead of using tags like `:release_1:', `:release_2:', it can be more efficient to use a property `Release' with a value `1.0' or `2.0'. Second, you can use @@ -3537,12 +3560,12 @@ File: org, Node: Dates and times, Next: Remember, Prev: Properties and column 8 Dates and Times ***************** -Items can be labeled with a date and/or a time to make them useful for -project planning. The specially formatted string carrying the date and -time information is called a _timestamp_ in Org-mode. This may be a -little confusing because timestamp is often used as indicating when -something was created or last changed. However, in Org-mode this term -is used in a much wider sense. +To assist project planning, TODO items can be labeled with a date and/or +a time. The specially formatted string carrying the date and time +information is called a _timestamp_ in Org-mode. This may be a little +confusing because timestamp is often used as indicating when something +was created or last changed. However, in Org-mode this term is used in +a much wider sense. * Menu: @@ -3609,8 +3632,8 @@ INACTIVE TIME STAMP ---------- Footnotes ---------- - (1) This is the standard ISO date/time format. If you cannot get -used to these, see *Note Custom time format:: + (1) This is the standard ISO date/time format. To use an +alternative format, see *Note Custom time format::.  File: org, Node: Creating timestamps, Next: Deadlines and scheduling, Prev: Time stamps, Up: Dates and times @@ -3798,16 +3821,17 @@ File: org, Node: Deadlines and scheduling, Next: Clocking work time, Prev: Cr 8.3 Deadlines and Scheduling ============================ -A time stamp may be preceded by special keywords to facilitate planning -of work: +A time stamp may be preceded by special keywords to facilitate planning: DEADLINE - The task (most likely a TODO item) is supposed to be finished on - that date, and it will be listed then. In addition, the - compilation for _today_ will carry a warning about the approaching - or missed deadline, starting `org-deadline-warning-days' before - the due date, and continuing until the entry is marked DONE. An - example: + Meaning: the task (most likely a TODO item, though not + necessarily) is supposed to be finished on that date. + + On the deadline date, the task will be listed in the agenda. In + addition, the agenda for _today_ will carry a warning about the + approaching or missed deadline, starting + `org-deadline-warning-days' before the due date, and continuing + until the entry is marked DONE. An example: *** TODO write article about the Earth for the Guide The editor in charge is [[bbdb:Ford Prefect]] @@ -3818,7 +3842,9 @@ DEADLINE warning period of 5 days `DEADLINE: <2004-02-29 Sun -5d>'. SCHEDULED - You are planning to start working on that task on the given date. + Meaning: you are planning to start working on that task on the + given date. + The headline will be listed under the given date(1). In addition, a reminder that the scheduled date has passed will be present in the compilation for _today_, until the entry is marked DONE. @@ -3828,12 +3854,12 @@ SCHEDULED SCHEDULED: <2004-12-25 Sat> Important: Scheduling an item in Org-mode should not be understood - like Scheduling a meeting. Setting a date for a meeting is just a - simple appointment, you should mark this entry with a simple plain - time stamp, to get this item shown on the date where it applies. - This is a frequent mis-understanding from Org-users. In Org-mode, - Scheduling means setting a date when you want to start working on - an action item. + in the same way that we understand scheduling a meeting. Setting + a date for a meeting is just a simple appointment, you should mark + this entry with a simple plain time stamp, to get this item shown + on the date where it applies. This is a frequent + mis-understanding from Org-users. In Org-mode, scheduling means + setting a date when you want to start working on an action item. * Menu: @@ -3880,11 +3906,14 @@ File: org, Node: Repeated tasks, Prev: Inserting deadline/schedule, Up: Deadl 8.3.2 Repeated Tasks -------------------- -Some tasks need to be repeated again and again, and Org-mode therefore -allows to use a repeater in a DEADLINE or SCHEDULED time stamp, for -example: +Some tasks need to be repeated again and again. Org-mode helps to +organize such tasks using a so-called repeater in a DEADLINE or +SCHEDULED time stamp. In the following example ** TODO Pay the rent DEADLINE: <2005-10-01 Sat +1m> + the `+1m' is a repeater; the intended interpretation is that the +task has a deadline on <2005-10-01> and repeats itself every (one) month +starting from that time. Deadlines and scheduled items produce entries in the agenda when they are over-due, so it is important to be able to mark such an entry as @@ -4110,6 +4139,9 @@ more than one template) and then prepare the buffer like During expansion of the template, special `%'-escapes allow dynamic insertion of content: %^{prompt} prompt the user for a string and replace this sequence with it. + You may specify a default value and a completion table with + %^{prompt|default|completion2|completion3...} + The arrow keys access a prompt-specific history. %t time stamp, date only %T time stamp with date and time %u, %U like the above, but inactive time stamps @@ -4126,6 +4158,8 @@ insertion of content: %:keyword specific information for certain link types, see below %[pathname] insert the contents of the file given by `pathname' %(sexp) evaluate elisp `(sexp)' and replace with the result + %! immediately store note after completing the template + (skipping the `C-c C-c' that normally triggers storing) For specific link types, the following keywords will be defined(1): @@ -4168,7 +4202,7 @@ When you are finished preparing a note with remember, you have to press `C-c C-c' to file the note away. The handler will store the note in the file and under the headline specified in the template, or it will use the default file and headlines. The window configuration will be -restored, and you are back in the working context before the call to +restored, sending you back to the working context before the call to `remember'. To re-use the location found during the last call to `remember', exit the remember buffer with `C-u C-u C-c C-c', i.e. specify a double prefix argument to `C-c C-c'. @@ -4248,8 +4282,8 @@ File: org, Node: Agenda views, Next: Embedded LaTeX, Prev: Remember, Up: Top Due to the way Org-mode works, TODO items, time-stamped items, and tagged headlines can be scattered throughout a file or even a number of -files. To get an overview over open action items, or over events that -are important for a particular date, this information must be collected, +files. To get an overview of open action items, or of events that are +important for a particular date, this information must be collected, sorted and displayed in an organized way. Org-mode can select items based on various criteria, and display them @@ -6883,18 +6917,17 @@ File: org, Node: TTY keys, Next: Interaction, Prev: Clean view, Up: Miscella 14.6 Using org-mode on a tty ============================ -Org-mode uses a number of keys that are not accessible on a tty. This -applies to most special keys like cursor keys, and , when -these are combined with modifier keys like and/or . -Org-mode uses these bindings because it needs to provide keys for a -large number of commands, and because these keys appeared particularly -easy to remember. In order to still be able to access the core -functionality of Org-mode on a tty, alternative bindings are provided. -Here is a complete list of these bindings, which are obviously more -cumbersome to use. Note that sometimes a work-around can be better. -For example changing a time stamp is really only fun with `S-' -keys. On a tty you would rather use `C-c .' to re-insert the -timestamp. +Because Org-mode contains a large number of commands, by default much of +Org-mode's core commands are bound to keys that are generally not +accessible on a tty, such as the cursor keys (, , , +), and , in particular when used together with +modifiers like and/or . To access these commands on a +tty when special keys are unavailable, the following alternative +bindings can be used. The tty bindings below will likely be more +cumbersome; you may find for some of the bindings below that a +customized work-around suits you better. For example, changing a time +stamp is really only fun with `S-' keys, whereas on a tty you +would rather use `C-c .' to re-insert the timestamp. Default Alternative 1 Alternative 2 `S-' `C-u ' @@ -7157,7 +7190,8 @@ The following extensions for Org-mode have been written by other people: `org-toc.el' by Bastien Guerry Produces a simple table of contents of an Org-mode file, for easy - navigation. `http://www.cognition.ens.fr/~guerry/u/org2rem.el'. + navigation. + `http://www.cognition.ens.fr/~guerry/u/org-registry.el'. `org-registry.el' by Bastien Guerry Find which Org-file link to a certain document. @@ -7717,7 +7751,7 @@ properties. Insert a property drawer at point.  -File: org, Node: History and Acknowledgments, Next: Main Index, Prev: Extensions and Hacking, Up: Top +File: org, Node: History and Acknowledgments, Next: Index, Prev: Extensions and Hacking, Up: Top Appendix B History and Acknowledgments ************************************** @@ -7888,10 +7922,10 @@ if I have forgotten someone, please accept my apologies and let me know. contributed various ideas and code snippets.  -File: org, Node: Main Index, Next: Key Index, Prev: History and Acknowledgments, Up: Top +File: org, Node: Index, Next: Key Index, Prev: History and Acknowledgments, Up: Top -Main Index -********** +The Main Index +************** [index] * Menu: @@ -7960,7 +7994,7 @@ Main Index * category, require for tags/property match: Tag searches. (line 69) * CDLaTeX: CDLaTeX mode. (line 6) * cdlatex.el: Cooperation. (line 29) -* checkbox statistics: Checkboxes. (line 23) +* checkbox statistics: Checkboxes. (line 25) * checkboxes: Checkboxes. (line 6) * children, subtree visibility state: Visibility cycling. (line 10) * clean outline view: Clean view. (line 6) @@ -7973,7 +8007,7 @@ Main Index * completion, of link abbreviations: Completion. (line 6) * completion, of links: Handling links. (line 25) * completion, of option keywords <1>: Completion. (line 6) -* completion, of option keywords <2>: Per file keywords. (line 23) +* completion, of option keywords <2>: Per-file keywords. (line 23) * completion, of option keywords: Export options. (line 6) * completion, of property keys: Completion. (line 6) * completion, of tags <1>: Completion. (line 6) @@ -8007,7 +8041,7 @@ Main Index (line 6) * dates: Dates and times. (line 6) * DEADLINE keyword: Deadlines and scheduling. - (line 10) + (line 9) * deadlines: Time stamps. (line 6) * debugging, of table formulas: Editing and debugging formulas. (line 97) @@ -8020,7 +8054,7 @@ Main 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 26) +* DONE, final TODO keyword: Per-file keywords. (line 26) * drawer, for properties: Property syntax. (line 6) * drawers: Drawers. (line 6) * dynamic blocks: Dynamic blocks. (line 6) @@ -8128,7 +8162,7 @@ Main Index * italic text: Enhancing text. (line 15) * jumping, to headlines: Motion. (line 6) * keybindings, global: Activation. (line 6) -* keyword options: Per file keywords. (line 6) +* keyword options: Per-file keywords. (line 6) * LaTeX class: Sectioning structure. (line 6) * LaTeX export: LaTeX export. (line 6) @@ -8219,12 +8253,12 @@ Main Index * overview, STARTUP keyword: In-buffer settings. (line 65) * packages, interaction with other: Interaction. (line 6) * pasting, of subtrees: Structure editing. (line 6) -* per file keywords: Per file keywords. (line 6) +* per-file keywords: Per-file keywords. (line 6) * plain lists: Plain lists. (line 6) * plain text external links: External links. (line 43) * presentation, of agenda items: Presentation and sorting. (line 6) -* printing sparse trees: Sparse trees. (line 46) +* printing sparse trees: Sparse trees. (line 47) * priorities: Priorities. (line 6) * priorities, of agenda items: Sorting of agenda items. (line 6) @@ -8269,7 +8303,7 @@ Main Index * richer text: Enhancing text. (line 6) * RMAIL links: External links. (line 6) * SCHEDULED keyword: Deadlines and scheduling. - (line 26) + (line 27) * scheduling: Time stamps. (line 6) * Scripts, for agenda processing: Extracting Agenda Information for other programs. (line 6) @@ -8289,14 +8323,14 @@ Main Index (line 6) * sparse tree, for deadlines: Inserting deadline/schedule. (line 13) -* sparse tree, for TODO: TODO basics. (line 38) +* sparse tree, for TODO: TODO basics. (line 37) * sparse tree, tag based: Tags. (line 6) * sparse trees: Sparse trees. (line 6) * special keywords: In-buffer settings. (line 6) * special strings: Export options. (line 26) * speedbar.el: Cooperation. (line 46) * spreadsheet capabilities: The spreadsheet. (line 6) -* statistics, for checkboxes: Checkboxes. (line 23) +* statistics, for checkboxes: Checkboxes. (line 25) * storing links: Handling links. (line 9) * structure editing: Structure editing. (line 6) * structure of document: Document structure. (line 6) @@ -8394,7 +8428,7 @@ Main Index * verbatim text: Enhancing text. (line 15) * visibility cycling: Visibility cycling. (line 6) * visibility cycling, drawers: Drawers. (line 6) -* visible text, printing: Sparse trees. (line 46) +* visible text, printing: Sparse trees. (line 47) * VM links: External links. (line 6) * WANDERLUST links: External links. (line 6) * weekly agenda: Weekly/Daily agenda. (line 6) @@ -8404,7 +8438,7 @@ Main Index * XOXO export: XOXO export. (line 6)  -File: org, Node: Key Index, Prev: Main Index, Up: Top +File: org, Node: Key Index, Prev: Index, Up: Top Key Index ********* @@ -8436,7 +8470,7 @@ Key Index * <1>: Editing and debugging formulas. (line 57) * <2>: Visibility cycling. (line 10) -* <3>: Plain lists. (line 41) +* <3>: Plain lists. (line 42) * <4>: Agenda commands. (line 33) * <5>: Setting tags. (line 68) * <6>: Built-in table editor. @@ -8461,7 +8495,7 @@ Key Index * C-_: Agenda commands. (line 108) * C-c ! <1>: Creating timestamps. (line 19) * C-c !: Footnotes. (line 14) -* C-c #: Checkboxes. (line 57) +* C-c #: Checkboxes. (line 60) * C-c %: Handling links. (line 82) * C-c &: Handling links. (line 86) * C-c ': Editing and debugging formulas. @@ -8469,8 +8503,8 @@ Key Index * C-c *: Updating the table. (line 13) * C-c +: Built-in table editor. (line 143) -* C-c ,: Priorities. (line 18) -* C-c - <1>: Plain lists. (line 88) +* C-c ,: Priorities. (line 21) +* C-c - <1>: Plain lists. (line 89) * C-c -: Built-in table editor. (line 92) * C-c .: Creating timestamps. (line 10) @@ -8480,7 +8514,7 @@ Key Index * C-c / p: Property searches. (line 23) * C-c / r: Sparse trees. (line 17) * C-c / T: Tag searches. (line 9) -* C-c / t: TODO basics. (line 38) +* C-c / t: TODO basics. (line 37) * C-c : <1>: Enhancing text. (line 34) * C-c :: Quoted examples. (line 15) * C-c ;: Comment lines. (line 10) @@ -8515,18 +8549,18 @@ Key Index * C-c a m: Matching tags and properties. (line 10) * C-c a t <1>: Global TODO list. (line 9) -* C-c a t: TODO basics. (line 49) +* C-c a t: TODO basics. (line 48) * C-c a T: Global TODO list. (line 14) * C-c C-a: Visibility cycling. (line 33) * C-c C-b: Motion. (line 15) * C-c C-c <1>: Built-in table editor. (line 56) * C-c C-c <2>: Property syntax. (line 58) -* C-c C-c <3>: Plain lists. (line 81) +* C-c C-c <3>: Plain lists. (line 82) * C-c C-c <4>: Processing LaTeX fragments. (line 15) * C-c C-c <5>: Cooperation. (line 63) -* C-c C-c <6>: Checkboxes. (line 37) +* C-c C-c <6>: Checkboxes. (line 40) * C-c C-c <7>: Cooperation. (line 54) * C-c C-c <8>: The very busy C-c C-c key. (line 6) @@ -8562,7 +8596,7 @@ Key Index (line 19) * C-c C-e t: Export options. (line 13) * C-c C-e v <1>: XOXO export. (line 11) -* C-c C-e v: Sparse trees. (line 46) +* C-c C-e v: Sparse trees. (line 47) * C-c C-e v a: ASCII export. (line 16) * C-c C-e v b: HTML Export commands. (line 24) @@ -8597,13 +8631,13 @@ Key Index * C-c C-t <1>: TODO basics. (line 13) * C-c C-t: Clocking work time. (line 30) * C-c C-u: Motion. (line 18) -* C-c C-v: TODO basics. (line 38) +* C-c C-v: TODO basics. (line 37) * C-c C-w <1>: Refiling notes. (line 13) * C-c C-w: Structure editing. (line 58) * C-c C-x <: Agenda files. (line 37) -* C-c C-x b: Visibility cycling. (line 41) +* C-c C-x b: Visibility cycling. (line 43) * C-c C-x C-a: ARCHIVE tag. (line 28) -* C-c C-x C-b: Checkboxes. (line 39) +* C-c C-x C-b: Checkboxes. (line 42) * C-c C-x C-c <1>: Using column view. (line 9) * C-c C-x C-c: Agenda commands. (line 223) * C-c C-x C-d: Clocking work time. (line 42) @@ -8696,7 +8730,7 @@ Key Index * M- <1>: Structure editing. (line 25) * M-: Built-in table editor. (line 74) -* M- <1>: Plain lists. (line 49) +* M- <1>: Plain lists. (line 50) * M-: Structure editing. (line 6) * M- <1>: Structure editing. (line 28) * M-: Built-in table editor. @@ -8704,7 +8738,7 @@ Key Index * M- <1>: Completion. (line 10) * M- <2>: Property syntax. (line 46) * M- <3>: Setting tags. (line 6) -* M- <4>: Per file keywords. (line 23) +* M- <4>: Per-file keywords. (line 23) * M-: Editing and debugging formulas. (line 64) * M- <1>: Built-in table editor. @@ -8715,25 +8749,25 @@ Key Index (line 89) * M-S- <2>: Editing and debugging formulas. (line 72) -* M-S- <3>: Plain lists. (line 66) +* M-S- <3>: Plain lists. (line 67) * M-S-: Structure editing. (line 40) -* M-S- <1>: Plain lists. (line 72) +* M-S- <1>: Plain lists. (line 73) * M-S- <2>: Built-in table editor. (line 76) * M-S- <3>: Structure editing. (line 31) * M-S-: The date/time prompt. (line 59) -* M-S- <1>: Checkboxes. (line 54) -* M-S- <2>: Plain lists. (line 59) +* M-S- <1>: Checkboxes. (line 57) +* M-S- <2>: Plain lists. (line 60) * M-S-: Structure editing. (line 22) * M-S- <1>: The date/time prompt. (line 59) -* M-S- <2>: Plain lists. (line 72) +* M-S- <2>: Plain lists. (line 73) * M-S- <3>: Structure editing. (line 34) * M-S-: Built-in table editor. (line 79) * M-S- <1>: Structure editing. (line 37) -* M-S- <2>: Plain lists. (line 66) +* M-S- <2>: Plain lists. (line 67) * M-S- <3>: Built-in table editor. (line 86) * M-S-: Editing and debugging formulas. @@ -8762,11 +8796,11 @@ Key Index * S- <1>: The date/time prompt. (line 59) * S- <2>: Creating timestamps. (line 40) -* S- <3>: Plain lists. (line 62) +* S- <3>: Plain lists. (line 63) * S- <4>: Editing and debugging formulas. (line 67) * S- <5>: Agenda commands. (line 151) -* S-: Priorities. (line 23) +* S-: Priorities. (line 26) * S- <1>: The date/time prompt. (line 59) * S- <2>: Agenda commands. (line 169) @@ -8794,16 +8828,16 @@ Key Index * S- <1>: Visibility cycling. (line 22) * S-: Built-in table editor. (line 61) -* S- <1>: Plain lists. (line 62) +* S- <1>: Plain lists. (line 63) * S- <2>: The date/time prompt. (line 59) * S- <3>: Editing and debugging formulas. (line 67) * S- <4>: Creating timestamps. (line 40) * S- <5>: Agenda commands. (line 145) -* S-: Priorities. (line 23) +* S-: Priorities. (line 26) * S-M-: Using column view. (line 61) -* S-M-: TODO basics. (line 57) +* S-M-: TODO basics. (line 55) * S-M-: Using column view. (line 58) * T: Agenda commands. (line 125) * t: Agenda commands. (line 112) @@ -8816,239 +8850,239 @@ Key Index  Tag Table: -Node: Top971 -Node: Introduction13456 -Node: Summary13942 -Node: Installation17079 -Node: Activation18457 -Node: Feedback19694 -Node: Conventions21783 -Node: Document structure22475 -Node: Outlines23367 -Node: Headlines24032 -Ref: Headlines-Footnote-125036 -Node: Visibility cycling25147 -Ref: Visibility cycling-Footnote-127357 -Ref: Visibility cycling-Footnote-227415 -Ref: Visibility cycling-Footnote-327465 -Node: Motion27735 -Node: Structure editing28689 -Node: Archiving31937 -Node: ARCHIVE tag32495 -Node: Moving subtrees34288 -Ref: Moving subtrees-Footnote-135835 -Node: Sparse trees36279 -Ref: Sparse trees-Footnote-138551 -Ref: Sparse trees-Footnote-238733 -Node: Plain lists38848 -Ref: Plain lists-Footnote-143045 -Ref: Plain lists-Footnote-243403 -Node: Drawers43584 -Ref: Drawers-Footnote-144461 -Node: orgstruct-mode44567 -Node: Tables45467 -Node: Built-in table editor46048 -Node: Narrow columns53465 -Ref: Narrow columns-Footnote-155400 -Node: Column groups55446 -Node: orgtbl-mode56979 -Node: The spreadsheet57782 -Node: References58869 -Ref: References-Footnote-163336 -Ref: References-Footnote-263477 -Node: Formula syntax for Calc63766 -Node: Formula syntax for Lisp66223 -Node: Field formulas67941 -Node: Column formulas69249 -Node: Editing and debugging formulas70848 -Node: Updating the table75001 -Node: Advanced features76054 -Node: Hyperlinks80579 -Node: Link format81357 -Node: Internal links82650 -Ref: Internal links-Footnote-184575 -Node: Radio targets84710 -Node: External links85410 -Node: Handling links87814 -Ref: Handling links-Footnote-193130 -Ref: Handling links-Footnote-293367 -Node: Using links outside Org-mode93441 -Node: Link abbreviations93951 -Node: Search options95644 -Ref: Search options-Footnote-197424 -Node: Custom searches97505 -Node: TODO items98536 -Node: TODO basics99574 -Node: TODO extensions101789 -Node: Workflow states102733 -Ref: Workflow states-Footnote-1103908 -Node: TODO types104001 -Ref: TODO types-Footnote-1105584 -Node: Multiple sets in one file105666 -Node: Fast access to TODO states107286 -Node: Per file keywords108429 -Ref: Per file keywords-Footnote-1109731 -Node: Faces for TODO keywords109932 -Node: Progress logging110638 -Node: Closing items111069 -Ref: Closing items-Footnote-1112003 -Ref: Closing items-Footnote-2112208 -Node: Tracking TODO state changes112281 -Ref: Tracking TODO state changes-Footnote-1113466 -Node: Priorities113541 -Ref: Priorities-Footnote-1115191 -Node: Breaking down tasks115261 -Ref: Breaking down tasks-Footnote-1115781 -Node: Checkboxes115877 -Node: Tags118726 -Node: Tag inheritance119498 -Node: Setting tags120435 -Ref: Setting tags-Footnote-1124958 -Ref: Setting tags-Footnote-2125070 -Node: Tag searches125153 -Node: Properties and columns127929 -Node: Property syntax129100 -Node: Special properties131790 -Node: Property searches132861 -Node: Property inheritance134122 -Node: Column view135569 -Node: Defining columns136803 -Node: Scope of column definitions137201 -Node: Column attributes138123 -Node: Using column view140519 -Node: Capturing Column View142600 -Node: Property API144327 -Node: Dates and times144681 -Node: Time stamps145410 -Ref: Time stamps-Footnote-1147774 -Node: Creating timestamps147890 -Node: The date/time prompt149969 -Ref: The date/time prompt-Footnote-1153325 -Ref: The date/time prompt-Footnote-2153381 -Ref: The date/time prompt-Footnote-3153487 -Node: Custom time format153580 -Node: Deadlines and scheduling155272 -Ref: Deadlines and scheduling-Footnote-1157350 -Node: Inserting deadline/schedule157505 -Node: Repeated tasks158623 -Ref: Repeated tasks-Footnote-1160301 -Node: Clocking work time160422 -Ref: Clocking work time-Footnote-1165274 -Ref: Clocking work time-Footnote-2165352 -Node: Remember165478 -Node: Setting up remember166424 -Ref: Setting up remember-Footnote-1167333 -Node: Remember templates167399 -Ref: Remember templates-Footnote-1171038 -Ref: Remember templates-Footnote-2171221 -Node: Storing notes171319 -Ref: Storing notes-Footnote-1173830 -Node: Refiling notes173932 -Node: Agenda views175197 -Node: Agenda files177148 -Ref: Agenda files-Footnote-1179589 -Ref: Agenda files-Footnote-2179738 -Node: Agenda dispatcher179931 -Ref: Agenda dispatcher-Footnote-1181985 -Ref: Agenda dispatcher-Footnote-2182079 -Node: Built-in agenda views182173 -Node: Weekly/Daily agenda182755 -Ref: Weekly/Daily agenda-Footnote-1186053 -Node: Global TODO list186257 -Node: Matching tags and properties188537 -Node: Timeline189628 -Node: Stuck projects190302 -Node: Presentation and sorting192155 -Node: Categories192948 -Ref: Categories-Footnote-1193659 -Node: Time-of-day specifications194096 -Node: Sorting of agenda items196069 -Node: Agenda commands197353 -Node: Custom agenda views204816 -Node: Storing searches205537 -Ref: Storing searches-Footnote-1208071 -Node: Block agenda208188 -Node: Setting Options209420 -Node: Exporting Agenda Views212161 -Ref: Exporting Agenda Views-Footnote-1216518 -Ref: Exporting Agenda Views-Footnote-2216575 -Node: Extracting Agenda Information for other programs216761 -Node: Embedded LaTeX220889 -Ref: Embedded LaTeX-Footnote-1221983 -Node: Math symbols222173 -Node: Subscripts and Superscripts222940 -Node: LaTeX fragments223786 -Ref: LaTeX fragments-Footnote-1226019 -Ref: LaTeX fragments-Footnote-2226280 -Node: Processing LaTeX fragments226414 -Node: CDLaTeX mode227362 -Ref: CDLaTeX mode-Footnote-1229848 -Node: Exporting229996 -Node: ASCII export231463 -Node: HTML export232964 -Node: HTML Export commands233590 -Node: Quoting HTML tags235377 -Node: Links236012 -Node: Images236709 -Ref: Images-Footnote-1237580 -Node: CSS support237641 -Ref: CSS support-Footnote-1238960 -Node: LaTeX export239073 -Node: LaTeX export commands239422 -Node: Quoting LaTeX code240584 -Node: Sectioning structure241118 -Node: XOXO export241619 -Node: iCalendar export242059 -Node: Text interpretation243528 -Node: Comment lines244183 -Node: Initial text244578 -Node: Footnotes246247 -Node: Quoted examples247039 -Node: Enhancing text247814 -Node: Export options250263 -Node: Publishing252724 -Ref: Publishing-Footnote-1253685 -Ref: Publishing-Footnote-2253829 -Node: Configuration253980 -Node: Project alist254698 -Node: Sources and destinations255764 -Node: Selecting files256494 -Node: Publishing action257242 -Node: Publishing options258576 -Node: Publishing links261082 -Node: Project page index262597 -Node: Sample configuration263375 -Node: Simple example263867 -Node: Complex example264540 -Node: Triggering publication266616 -Node: Miscellaneous267301 -Node: Completion267935 -Node: Customization269605 -Node: In-buffer settings270188 -Node: The very busy C-c C-c key275858 -Node: Clean view277713 -Node: TTY keys280290 -Node: Interaction281900 -Node: Cooperation282297 -Node: Conflicts285968 -Node: Bugs287978 -Node: Extensions and Hacking289474 -Node: Extensions290199 -Node: Adding hyperlink types292461 -Node: Tables in arbitrary syntax296123 -Node: Radio tables297515 -Node: A LaTeX example300018 -Ref: A LaTeX example-Footnote-1303696 -Ref: A LaTeX example-Footnote-2303844 -Node: Translator functions304279 -Ref: Translator functions-Footnote-1307408 -Node: Radio lists307496 -Ref: Radio lists-Footnote-1308618 -Node: Dynamic blocks308738 -Node: Special agenda views310710 -Node: Using the property API313955 -Node: History and Acknowledgments315553 -Node: Main Index322239 -Node: Key Index358970 +Node: Top970 +Node: Introduction13486 +Node: Summary13972 +Node: Installation17109 +Node: Activation18487 +Node: Feedback19724 +Node: Conventions21813 +Node: Document structure22497 +Node: Outlines23389 +Node: Headlines24054 +Ref: Headlines-Footnote-125058 +Node: Visibility cycling25169 +Ref: Visibility cycling-Footnote-127399 +Ref: Visibility cycling-Footnote-227457 +Ref: Visibility cycling-Footnote-327507 +Node: Motion27777 +Node: Structure editing28731 +Node: Archiving31979 +Node: ARCHIVE tag32537 +Node: Moving subtrees34330 +Ref: Moving subtrees-Footnote-135877 +Node: Sparse trees36321 +Ref: Sparse trees-Footnote-138573 +Ref: Sparse trees-Footnote-238755 +Node: Plain lists38870 +Ref: Plain lists-Footnote-143129 +Ref: Plain lists-Footnote-243487 +Node: Drawers43668 +Ref: Drawers-Footnote-144549 +Node: orgstruct-mode44654 +Node: Tables45554 +Node: Built-in table editor46155 +Node: Narrow columns53572 +Ref: Narrow columns-Footnote-155507 +Node: Column groups55553 +Node: orgtbl-mode57086 +Node: The spreadsheet57889 +Node: References58976 +Ref: References-Footnote-163443 +Ref: References-Footnote-263584 +Node: Formula syntax for Calc63873 +Node: Formula syntax for Lisp66330 +Node: Field formulas68048 +Node: Column formulas69356 +Node: Editing and debugging formulas70955 +Node: Updating the table75108 +Node: Advanced features76161 +Node: Hyperlinks80686 +Node: Link format81455 +Node: Internal links82748 +Ref: Internal links-Footnote-184673 +Node: Radio targets84808 +Node: External links85508 +Node: Handling links87912 +Ref: Handling links-Footnote-193228 +Ref: Handling links-Footnote-293465 +Node: Using links outside Org-mode93539 +Node: Link abbreviations94049 +Node: Search options95742 +Ref: Search options-Footnote-197522 +Node: Custom searches97603 +Node: TODO items98634 +Node: TODO basics99704 +Node: TODO extensions101897 +Node: Workflow states102856 +Ref: Workflow states-Footnote-1104031 +Node: TODO types104124 +Ref: TODO types-Footnote-1105707 +Node: Multiple sets in one file105789 +Node: Fast access to TODO states107409 +Node: Per-file keywords108552 +Ref: Per-file keywords-Footnote-1109854 +Node: Faces for TODO keywords110055 +Node: Progress logging110761 +Node: Closing items111192 +Ref: Closing items-Footnote-1112126 +Ref: Closing items-Footnote-2112331 +Node: Tracking TODO state changes112404 +Ref: Tracking TODO state changes-Footnote-1113589 +Node: Priorities113664 +Ref: Priorities-Footnote-1115459 +Node: Breaking down tasks115529 +Ref: Breaking down tasks-Footnote-1116049 +Node: Checkboxes116145 +Node: Tags119084 +Node: Tag inheritance119839 +Node: Setting tags120885 +Ref: Setting tags-Footnote-1125403 +Ref: Setting tags-Footnote-2125515 +Node: Tag searches125598 +Node: Properties and columns128377 +Node: Property syntax130288 +Node: Special properties132978 +Node: Property searches134049 +Node: Property inheritance135310 +Node: Column view136757 +Node: Defining columns137991 +Node: Scope of column definitions138389 +Node: Column attributes139311 +Node: Using column view141707 +Node: Capturing Column View143788 +Node: Property API145515 +Node: Dates and times145869 +Node: Time stamps146590 +Ref: Time stamps-Footnote-1148954 +Node: Creating timestamps149068 +Node: The date/time prompt151147 +Ref: The date/time prompt-Footnote-1154503 +Ref: The date/time prompt-Footnote-2154559 +Ref: The date/time prompt-Footnote-3154665 +Node: Custom time format154758 +Node: Deadlines and scheduling156450 +Ref: Deadlines and scheduling-Footnote-1158633 +Node: Inserting deadline/schedule158788 +Node: Repeated tasks159906 +Ref: Repeated tasks-Footnote-1161781 +Node: Clocking work time161902 +Ref: Clocking work time-Footnote-1166754 +Ref: Clocking work time-Footnote-2166832 +Node: Remember166958 +Node: Setting up remember167904 +Ref: Setting up remember-Footnote-1168813 +Node: Remember templates168879 +Ref: Remember templates-Footnote-1172867 +Ref: Remember templates-Footnote-2173050 +Node: Storing notes173148 +Ref: Storing notes-Footnote-1175659 +Node: Refiling notes175761 +Node: Agenda views177026 +Node: Agenda files178973 +Ref: Agenda files-Footnote-1181414 +Ref: Agenda files-Footnote-2181563 +Node: Agenda dispatcher181756 +Ref: Agenda dispatcher-Footnote-1183810 +Ref: Agenda dispatcher-Footnote-2183904 +Node: Built-in agenda views183998 +Node: Weekly/Daily agenda184580 +Ref: Weekly/Daily agenda-Footnote-1187878 +Node: Global TODO list188082 +Node: Matching tags and properties190362 +Node: Timeline191453 +Node: Stuck projects192127 +Node: Presentation and sorting193980 +Node: Categories194773 +Ref: Categories-Footnote-1195484 +Node: Time-of-day specifications195921 +Node: Sorting of agenda items197894 +Node: Agenda commands199178 +Node: Custom agenda views206641 +Node: Storing searches207362 +Ref: Storing searches-Footnote-1209896 +Node: Block agenda210013 +Node: Setting Options211245 +Node: Exporting Agenda Views213986 +Ref: Exporting Agenda Views-Footnote-1218343 +Ref: Exporting Agenda Views-Footnote-2218400 +Node: Extracting Agenda Information for other programs218586 +Node: Embedded LaTeX222714 +Ref: Embedded LaTeX-Footnote-1223808 +Node: Math symbols223998 +Node: Subscripts and Superscripts224765 +Node: LaTeX fragments225611 +Ref: LaTeX fragments-Footnote-1227844 +Ref: LaTeX fragments-Footnote-2228105 +Node: Processing LaTeX fragments228239 +Node: CDLaTeX mode229187 +Ref: CDLaTeX mode-Footnote-1231673 +Node: Exporting231821 +Node: ASCII export233288 +Node: HTML export234789 +Node: HTML Export commands235415 +Node: Quoting HTML tags237202 +Node: Links237837 +Node: Images238534 +Ref: Images-Footnote-1239405 +Node: CSS support239466 +Ref: CSS support-Footnote-1240785 +Node: LaTeX export240898 +Node: LaTeX export commands241247 +Node: Quoting LaTeX code242409 +Node: Sectioning structure242943 +Node: XOXO export243444 +Node: iCalendar export243884 +Node: Text interpretation245353 +Node: Comment lines246008 +Node: Initial text246403 +Node: Footnotes248072 +Node: Quoted examples248864 +Node: Enhancing text249639 +Node: Export options252088 +Node: Publishing254549 +Ref: Publishing-Footnote-1255510 +Ref: Publishing-Footnote-2255654 +Node: Configuration255805 +Node: Project alist256523 +Node: Sources and destinations257589 +Node: Selecting files258319 +Node: Publishing action259067 +Node: Publishing options260401 +Node: Publishing links262907 +Node: Project page index264422 +Node: Sample configuration265200 +Node: Simple example265692 +Node: Complex example266365 +Node: Triggering publication268441 +Node: Miscellaneous269126 +Node: Completion269760 +Node: Customization271430 +Node: In-buffer settings272013 +Node: The very busy C-c C-c key277683 +Node: Clean view279538 +Node: TTY keys282115 +Node: Interaction283692 +Node: Cooperation284089 +Node: Conflicts287760 +Node: Bugs289770 +Node: Extensions and Hacking291266 +Node: Extensions291991 +Node: Adding hyperlink types294263 +Node: Tables in arbitrary syntax297925 +Node: Radio tables299317 +Node: A LaTeX example301820 +Ref: A LaTeX example-Footnote-1305498 +Ref: A LaTeX example-Footnote-2305646 +Node: Translator functions306081 +Ref: Translator functions-Footnote-1309210 +Node: Radio lists309298 +Ref: Radio lists-Footnote-1310420 +Node: Dynamic blocks310540 +Node: Special agenda views312512 +Node: Using the property API315757 +Node: History and Acknowledgments317355 +Node: Index324036 +Node: Key Index360770  End Tag Table diff --git a/org-install.el b/org-install.el index 0dcf5dd64..831400494 100644 --- a/org-install.el +++ b/org-install.el @@ -8,7 +8,7 @@ ;;;;;; org-remember-insinuate org-open-at-point-global org-insert-link-global ;;;;;; org-store-link orgtbl-mode turn-on-orgtbl org-run-like-in-org-mode ;;;;;; turn-on-orgstruct++ turn-on-orgstruct orgstruct-mode org-global-cycle -;;;;;; org-cycle org-mode) "org" "org.el" (18260 13209)) +;;;;;; org-cycle org-mode) "org" "org.el" (18281 37899)) ;;; Generated autoloads from org.el (autoload (quote org-mode) "org" "\ @@ -28,7 +28,9 @@ can be exported as a structured ASCII or HTML file. The following commands are available: -\\{org-mode-map}" t nil) +\\{org-mode-map} + +\(fn)" t nil) (autoload (quote org-cycle) "org" "\ Visibility cycling for Org-mode. @@ -57,10 +59,14 @@ Visibility cycling for Org-mode. - Special case: if point is at the beginning of the buffer and there is no headline in line 1, this function will act as if called with prefix arg. - But only if also the variable `org-cycle-global-at-bob' is t." t nil) + But only if also the variable `org-cycle-global-at-bob' is t. + +\(fn &optional ARG)" t nil) (autoload (quote org-global-cycle) "org" "\ -Cycle the global visibility. For details see `org-cycle'." t nil) +Cycle the global visibility. For details see `org-cycle'. + +\(fn &optional ARG)" t nil) (autoload (quote orgstruct-mode) "org" "\ Toggle the minor more `orgstruct-mode'. @@ -83,24 +89,37 @@ C-c - Cycle list bullet TAB Cycle item visibility M-RET Insert new heading/item S-M-RET Insert new TODO heading / Chekbox item -C-c C-c Set tags / toggle checkbox" t nil) +C-c C-c Set tags / toggle checkbox + +\(fn &optional ARG)" t nil) (autoload (quote turn-on-orgstruct) "org" "\ -Unconditionally turn on `orgstruct-mode'." nil nil) +Unconditionally turn on `orgstruct-mode'. + +\(fn)" nil nil) (autoload (quote turn-on-orgstruct++) "org" "\ Unconditionally turn on `orgstruct-mode', and force org-mode indentations. In addition to setting orgstruct-mode, this also exports all indentation and autofilling variables from org-mode into the buffer. Note that turning -off orgstruct-mode will *not* remove these additonal settings." nil nil) +off orgstruct-mode will *not* remove these additonal settings. -(autoload (quote org-run-like-in-org-mode) "org" nil nil nil) +\(fn)" nil nil) + +(autoload (quote org-run-like-in-org-mode) "org" "\ +Not documented + +\(fn CMD)" nil nil) (autoload (quote turn-on-orgtbl) "org" "\ -Unconditionally turn on `orgtbl-mode'." nil nil) +Unconditionally turn on `orgtbl-mode'. + +\(fn)" nil nil) (autoload (quote orgtbl-mode) "org" "\ -The `org-mode' table editor as a minor mode for use in other modes." t nil) +The `org-mode' table editor as a minor mode for use in other modes. + +\(fn &optional ARG)" t nil) (autoload (quote org-store-link) "org" "\ \\Store an org-link to the current location. @@ -108,30 +127,42 @@ This link can later be inserted into an org-buffer with \\[org-insert-link]. For some link types, a prefix arg is interpreted: For links to usenet articles, arg negates `org-usenet-links-prefer-google'. -For file links, arg negates `org-context-in-file-links'." t nil) +For file links, arg negates `org-context-in-file-links'. + +\(fn ARG)" t nil) (autoload (quote org-insert-link-global) "org" "\ Insert a link like Org-mode does. -This command can be called in any mode to insert a link in Org-mode syntax." t nil) +This command can be called in any mode to insert a link in Org-mode syntax. + +\(fn)" t nil) (autoload (quote org-open-at-point-global) "org" "\ Follow a link like Org-mode does. This command can be called in any mode to follow a link that has -Org-mode syntax." t nil) +Org-mode syntax. + +\(fn)" t nil) (autoload (quote org-remember-insinuate) "org" "\ -Setup remember.el for use wiht Org-mode." nil nil) +Setup remember.el for use wiht Org-mode. + +\(fn)" nil nil) (autoload (quote org-remember-annotation) "org" "\ Return a link to the current location as an annotation for remember.el. If you are using Org-mode files as target for data storage with remember.el, then the annotations should include a link compatible with the -conventions in Org-mode. This function returns such a link." nil nil) +conventions in Org-mode. This function returns such a link. + +\(fn)" nil nil) (autoload (quote org-remember-apply-template) "org" "\ Initialize *remember* buffer with template, invoke `org-mode'. This function should be placed into `remember-mode-hook' and in fact requires -to be run from that hook to function properly." nil nil) +to be run from that hook to function properly. + +\(fn &optional USE-CHAR SKIP-INTERACTIVE)" nil nil) (autoload (quote org-remember) "org" "\ Call `remember'. If this is already a remember buffer, re-apply template. @@ -140,10 +171,13 @@ of the remember buffer. When called interactively with a `C-u' prefix argument GOTO, don't remember anything, just go to the file/headline where the selected templated usually -stores its notes. +stores its notes. With a double prefix arg `C-u C-u', got to the last +note stored by remember. Lisp programs can set ORG-FORCE-REMEMBER-TEMPLATE-CHAR to a character -associated with a template in `org-remember-tempates'." t nil) +associated with a template in `org-remember-tempates'. + +\(fn &optional GOTO ORG-FORCE-REMEMBER-TEMPLATE-CHAR)" t nil) (autoload (quote org-remember-handler) "org" "\ Store stuff from remember.el into an org file. @@ -179,7 +213,9 @@ If the variable `org-adapt-indentation' is non-nil, the entire text is also indented so that it starts in the same column as the headline \(i.e. after the stars). -See also the variable `org-reverse-note-order'." nil nil) +See also the variable `org-reverse-note-order'. + +\(fn)" nil nil) (autoload (quote org-agenda-to-appt) "org" "\ Activate appointments found in `org-agenda-files'. @@ -196,7 +232,9 @@ either 'headline or 'category. For example: (category \"Work\")) will only add headlines containing IMPORTANT or headlines -belonging to the category \"Work\"." t nil) +belonging to the category \"Work\". + +\(fn &optional FILTER)" t nil) (autoload (quote org-agenda) "org" "\ Dispatch agenda commands to collect entries to the agenda buffer. @@ -221,7 +259,9 @@ If the current buffer is in Org-mode and visiting a file, you can also first press `<' once to indicate that the agenda should be temporarily \(until the next use of \\[org-agenda]) restricted to the current file. Pressing `<' twice means to restrict to the current subtree or region -\(if active)." t nil) +\(if active). + +\(fn ARG &optional KEYS RESTRICTION)" t nil) (autoload (quote org-batch-agenda) "org" "\ Run an agenda command in batch mode and send the result to STDOUT. @@ -229,7 +269,9 @@ If CMD-KEY is a string of length 1, it is used as a key in `org-agenda-custom-commands' and triggers this command. If it is a longer string is is used as a tags/todo match string. Paramters are alternating variable names and values that will be bound -before running the agenda command." nil (quote macro)) +before running the agenda command. + +\(fn CMD-KEY &rest PARAMETERS)" nil (quote macro)) (autoload (quote org-batch-agenda-csv) "org" "\ Run an agenda command in batch mode and send the result to STDOUT. @@ -264,17 +306,26 @@ time The time, like 15:00-16:50 extra Sting with extra planning info priority-l The priority letter if any was given priority-n The computed numerical priority -agenda-day The day in the agenda where this is listed" nil (quote macro)) +agenda-day The day in the agenda where this is listed -(autoload (quote org-store-agenda-views) "org" nil t nil) +\(fn CMD-KEY &rest PARAMETERS)" nil (quote macro)) + +(autoload (quote org-store-agenda-views) "org" "\ +Not documented + +\(fn &rest PARAMETERS)" t nil) (autoload (quote org-batch-store-agenda-views) "org" "\ -Run all custom agenda commands that have a file argument." nil (quote macro)) +Run all custom agenda commands that have a file argument. + +\(fn &rest PARAMETERS)" nil (quote macro)) (autoload (quote org-cycle-agenda-files) "org" "\ Cycle through the files in `org-agenda-files'. If the current buffer visits an agenda file, find the next one in the list. -If the current buffer does not, find the first agenda file." t nil) +If the current buffer does not, find the first agenda file. + +\(fn)" t nil) (autoload (quote org-agenda-list) "org" "\ Produce a daily/weekly view from all files in variable `org-agenda-files'. @@ -291,25 +342,33 @@ span INCLUDE-ALL days. Lisp programs should instead specify NDAYS to change the number of days. NDAYS defaults to `org-agenda-ndays'. START-DAY defaults to TODAY, or to the most recent match for the weekday -given in `org-agenda-start-on-weekday'." t nil) +given in `org-agenda-start-on-weekday'. + +\(fn &optional INCLUDE-ALL START-DAY NDAYS)" t nil) (autoload (quote org-todo-list) "org" "\ Show all TODO entries from all agenda file in a single list. 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-1'." t nil) +`org-todo-keywords-1'. + +\(fn ARG)" t nil) (autoload (quote org-tags-view) "org" "\ Show all headlines for all `org-agenda-files' matching a TAGS criterion. -The prefix arg TODO-ONLY limits the search to TODO entries." t nil) +The prefix arg TODO-ONLY limits the search to TODO entries. + +\(fn &optional TODO-ONLY MATCH)" t nil) (autoload (quote org-agenda-list-stuck-projects) "org" "\ Create agenda view for projects that are stuck. Stuck projects are project that have no next actions. For the definitions of what a project is and how to check if it stuck, customize the variable `org-stuck-projects'. -MATCH is being ignored." t nil) +MATCH is being ignored. + +\(fn &rest IGNORE)" t nil) (autoload (quote org-diary) "org" "\ Return diary information from org-files. @@ -355,21 +414,29 @@ So the example above may also be written as The function expects the lisp variables `entry' and `date' to be provided by the caller, because this is how the calendar works. Don't use this -function from a program - use `org-agenda-get-day-entries' instead." nil nil) +function from a program - use `org-agenda-get-day-entries' instead. + +\(fn &rest ARGS)" nil nil) (autoload (quote org-export-icalendar-this-file) "org" "\ Export current file as an iCalendar file. The iCalendar file will be located in the same directory as the Org-mode -file, but with extension `.ics'." t nil) +file, but with extension `.ics'. + +\(fn)" t nil) (autoload (quote org-export-icalendar-all-agenda-files) "org" "\ Export all files in `org-agenda-files' to iCalendar .ics files. Each iCalendar file will be located in the same directory as the Org-mode -file, but with extension `.ics'." t nil) +file, but with extension `.ics'. + +\(fn)" t nil) (autoload (quote org-export-icalendar-combine-agenda-files) "org" "\ Export all files in `org-agenda-files' to a single combined iCalendar file. -The file is stored under the name `org-combined-agenda-icalendar-file'." t nil) +The file is stored under the name `org-combined-agenda-icalendar-file'. + +\(fn)" t nil) ;;;*** @@ -378,19 +445,27 @@ The file is stored under the name `org-combined-agenda-icalendar-file'." t nil) ;;; Generated autoloads from org-publish.el (autoload (quote org-publish) "org-publish" "\ -Publish the project PROJECT-NAME." t nil) +Publish the project PROJECT-NAME. + +\(fn PROJECT-NAME &optional FORCE)" t nil) (autoload (quote org-publish-current-project) "org-publish" "\ Publish the project associated with the current file. -With prefix argument, force publishing all files in project." t nil) +With prefix argument, force publishing all files in project. + +\(fn &optional FORCE)" t nil) (autoload (quote org-publish-current-file) "org-publish" "\ Publish the current file. -With prefix argument, force publish the file." t nil) +With prefix argument, force publish the file. + +\(fn &optional FORCE)" t nil) (autoload (quote org-publish-all) "org-publish" "\ Publish all projects. -With prefix argument, force publish all files." t nil) +With prefix argument, force publish all files. + +\(fn &optional FORCE)" t nil) ;;;*** @@ -405,18 +480,24 @@ Call `org-export-as-latex', may be used in batch processing as emacs --batch --load=$HOME/lib/emacs/org.el --eval \"(setq org-export-headline-levels 2)\" - --visit=MyFile --funcall org-export-as-latex-batch" nil nil) + --visit=MyFile --funcall org-export-as-latex-batch + +\(fn)" nil nil) (autoload (quote org-export-as-latex-to-buffer) "org-export-latex" "\ Call `org-exort-as-latex` with output to a temporary buffer. -No file is created. The prefix ARG is passed through to `org-export-as-latex'." t nil) +No file is created. The prefix ARG is passed through to `org-export-as-latex'. + +\(fn ARG)" t nil) (autoload (quote org-replace-region-by-latex) "org-export-latex" "\ Replace the region from BEG to END with its LaTeX export. It assumes the region has `org-mode' syntax, and then convert it to LaTeX. This can be used in any buffer. For example, you could write an itemized list in `org-mode' syntax in an LaTeX buffer and -then use this command to convert it." t nil) +then use this command to convert it. + +\(fn BEG END)" t nil) (autoload (quote org-export-region-as-latex) "org-export-latex" "\ Convert region from BEG to END in `org-mode' buffer to LaTeX. @@ -431,7 +512,9 @@ a Lisp program could call this function in the following way: (setq latex (org-export-region-as-latex beg end t 'string)) When called interactively, the output buffer is selected, and shown -in a window. A non-interactive call will only retunr the buffer." t nil) +in a window. A non-interactive call will only retunr the buffer. + +\(fn BEG END &optional BODY-ONLY BUFFER)" t nil) (autoload (quote org-export-as-latex) "org-export-latex" "\ Export current buffer to a LaTeX file. @@ -448,7 +531,9 @@ buffer. If TO-BUFFER is the symbol `string', don't leave any buffer behind but just return the resulting LaTeX as a string. When BODY-ONLY is set, don't produce the file header and footer, simply return the content of egin{document}...nd{document}, -without even the egin{document} and nd{document} commands." t nil) +without even the egin{document} and nd{document} commands. + +\(fn ARG &optional HIDDEN EXT-PLIST TO-BUFFER BODY-ONLY)" t nil) ;;;*** diff --git a/org.el b/org.el index f01936d80..7c589f2d4 100644 --- a/org.el +++ b/org.el @@ -5,7 +5,7 @@ ;; Author: Carsten Dominik ;; Keywords: outlines, hypermedia, calendar, wp ;; Homepage: http://orgmode.org -;; Version: 5.16b +;; Version: 5.17 ;; ;; This file is part of GNU Emacs. ;; @@ -84,7 +84,7 @@ ;;; Version -(defconst org-version "5.16a" +(defconst org-version "5.17" "The version number of the file org.el.") (defun org-version () (interactive) @@ -1436,7 +1436,9 @@ The template specifies the structure of the remember buffer. It should have a first line starting with a star, to act as the org-mode headline. Furthermore, the following %-escapes will be replaced with content: - %^{prompt} prompt the user for a string and replace this sequence with it. + %^{prompt} Prompt the user for a string and replace this sequence with it. + A default value and a completion table ca be specified like this: + %^{prompt|default|completion2|completion3|...} %t time stamp, date only %T time stamp with date and time %u, %U like the above, but inactive time stamps @@ -1447,6 +1449,13 @@ Furthermore, the following %-escapes will be replaced with content: %i initial content, the region when remember is called with C-u. If %i is indented, the entire inserted text will be indented as well. + %c content of the clipboard, or current kill ring head + %^g prompt for tags, with completion on tags in target file + %^G prompt for tags, with completion all tags in all agenda files + %:keyword specific information for certain link types, see below + %[pathname] insert the contents of the file given by `pathname' + %(sexp) evaluate elisp `(sexp)' and replace with the result + %? After completing the template, position cursor here. @@ -1516,9 +1525,10 @@ This is list of cons cells. Each cell contains: todo keyword. - a cons cell (:regexp . \"REGEXP\") with a regular expression matching headlines that are refiling targets. - - a cons cell (:level . N). Any headline of level N is considered a target." + - a cons cell (:level . N). Any headline of level N is considered a target. + - a cons cell (:maxlevel . N). Any headline with level <= N is a target." ;; FIXME: what if there are a var and func with same name??? - :group 'org + :group 'org-remember :type '(repeat (cons (choice :value org-agenda-files @@ -1529,7 +1539,14 @@ This is list of cons cells. Each cell contains: (cons :tag "Specific tag" (const :tag) (string)) (cons :tag "TODO keyword" (const :todo) (string)) (cons :tag "Regular expression" (const :regexp) (regexp)) - (cons :tag "Level number" (const :level) (integer)))))) + (cons :tag "Level number" (const :level) (integer)) + (cons :tag "Max Level number" (const :maxlevel) (integer)))))) + +(defcustom org-refile-use-outline-path nil + "Non-nil means, provide refile targets as paths. +So a level 3 headline will be available as level1/level2/level3." + :group 'org-remember + :type 'boolean) (defgroup org-todo nil "Options concerning TODO items in Org-mode." @@ -4036,6 +4053,131 @@ If it is less than 8, the level-1 face gets re-used for level N+1 etc." :type 'number :group 'org-faces) +;;; Functions and variables from ther packages +;; Declared here to avoid compiler warnings + +(unless (fboundp 'declare-function) (defmacro declare-function (&rest args))) + +;; XEmacs only +(defvar outline-mode-menu-heading) +(defvar outline-mode-menu-show) +(defvar outline-mode-menu-hide) +(defvar zmacs-regions) ; XEmacs regions + +;; Emacs only +(defvar mark-active) + +;; Various packages +;; FIXME: get the argument lists for the UNKNOWN stuff +(declare-function add-to-diary-list "diary-lib" + (date string specifier &optional marker globcolor literal)) +(declare-function table--at-cell-p "table" (position &optional object at-column)) +(declare-function Info-find-node "info" (filename nodename &optional no-going-back)) +(declare-function Info-goto-node "info" (nodename &optional fork)) +(declare-function bbdb "ext:bbdb-com" (string elidep)) +(declare-function bbdb-company "ext:bbdb-com" (string elidep)) +(declare-function bbdb-current-record "ext:bbdb-com" (&optional planning-on-modifying)) +(declare-function bbdb-name "ext:bbdb-com" (string elidep)) +(declare-function bbdb-record-getprop "ext:bbdb" (record property)) +(declare-function bbdb-record-name "ext:bbdb" (record)) +(declare-function bibtex-beginning-of-entry "bibtex" ()) +(declare-function bibtex-generate-autokey "bibtex" ()) +(declare-function bibtex-parse-entry "bibtex" (&optional content)) +(declare-function bibtex-url "bibtex" (&optional pos no-browse)) +(defvar calc-embedded-close-formula) +(defvar calc-embedded-open-formula) +(declare-function calendar-astro-date-string "cal-julian" (&optional date)) +(declare-function calendar-bahai-date-string "cal-bahai" (&optional date)) +(declare-function calendar-check-holidays "holidays" (date)) +(declare-function calendar-chinese-date-string "cal-china" (&optional date)) +(declare-function calendar-coptic-date-string "cal-coptic" (&optional date)) +(declare-function calendar-ethiopic-date-string "cal-coptic" (&optional date)) +(declare-function calendar-forward-day "cal-move" (arg)) +(declare-function calendar-french-date-string "cal-french" (&optional date)) +(declare-function calendar-goto-date "cal-move" (date)) +(declare-function calendar-goto-today "cal-move" ()) +(declare-function calendar-hebrew-date-string "cal-hebrew" (&optional date)) +(declare-function calendar-islamic-date-string "cal-islam" (&optional date)) +(declare-function calendar-iso-date-string "cal-iso" (&optional date)) +(declare-function calendar-julian-date-string "cal-julian" (&optional date)) +(declare-function calendar-mayan-date-string "cal-mayan" (&optional date)) +(declare-function calendar-persian-date-string "cal-persia" (&optional date)) +(defvar calendar-mode-map) +(defvar original-date) ; dynamically scoped in calendar.el does scope this +(declare-function cdlatex-tab "ext:cdlatex" ()) +(declare-function dired-get-filename "dired" (&optional localp no-error-if-not-filep)) +(declare-function elmo-folder-exists-p "ext:elmo" (folder) t) +(declare-function elmo-message-entity-field "ext:elmo-msgdb" (entity field &optional type)) +(declare-function elmo-message-field "ext:elmo" (folder number field &optional type) t) +(declare-function elmo-msgdb-overview-get-entity "ext:elmo" (&rest unknown) t) +(defvar font-lock-unfontify-region-function) +(declare-function gnus-article-show-summary "gnus-art" ()) +(declare-function gnus-summary-last-subject "gnus-sum" ()) +(defvar gnus-other-frame-object) +(defvar gnus-group-name) +(defvar gnus-article-current) +(defvar Info-current-file) +(defvar Info-current-node) +(declare-function mh-display-msg "mh-show" (msg-num folder-name)) +(declare-function mh-find-path "mh-utils" ()) +(declare-function mh-get-header-field "mh-utils" (field)) +(declare-function mh-get-msg-num "mh-utils" (error-if-no-message)) +(declare-function mh-header-display "mh-show" ()) +(declare-function mh-index-previous-folder "mh-search" ()) +(declare-function mh-normalize-folder-name "mh-utils" (folder &optional empty-string-okay dont-remove-trailing-slash return-nil-if-folder-empty)) +(declare-function mh-search "mh-search" (folder search-regexp &optional redo-search-flag window-config)) +(declare-function mh-search-choose "mh-search" (&optional searcher)) +(declare-function mh-show "mh-show" (&optional message redisplay-flag)) +(declare-function mh-show-buffer-message-number "mh-comp" (&optional buffer)) +(declare-function mh-show-header-display "mh-show" t t) +(declare-function mh-show-msg "mh-show" (msg)) +(declare-function mh-show-show "mh-show" t t) +(declare-function mh-visit-folder "mh-folder" (folder &optional range index-data)) +(defvar mh-progs) +(defvar mh-current-folder) +(defvar mh-show-folder-buffer) +(defvar mh-index-folder) +(defvar mh-searcher) +(declare-function org-export-latex-cleaned-string "org-export-latex" (&optional commentsp)) +(declare-function parse-time-string "parse-time" (string)) +(declare-function remember "remember" (&optional initial)) +(declare-function remember-buffer-desc "remember" ()) +(defvar remember-save-after-remembering) +(defvar remember-data-file) +(defvar remember-register) +(defvar remember-buffer) +(declare-function rmail-narrow-to-non-pruned-header "rmail" ()) +(declare-function rmail-show-message "rmail" (&optional n no-summary)) +(declare-function rmail-what-message "rmail" ()) +(defvar texmathp-why) +(declare-function vm-beginning-of-message "ext:vm-page" ()) +(declare-function vm-follow-summary-cursor "ext:vm-motion" ()) +(declare-function vm-get-header-contents "ext:vm-summary" (message header-name-regexp &optional clump-sep)) +(declare-function vm-isearch-narrow "ext:vm-search" ()) +(declare-function vm-isearch-update "ext:vm-search" ()) +(declare-function vm-select-folder-buffer "ext:vm-macro" ()) +(declare-function vm-su-message-id "ext:vm-summary" (m)) +(declare-function vm-su-subject "ext:vm-summary" (m)) +(declare-function vm-summarize "ext:vm-summary" (&optional display raise)) +(defvar vm-message-pointer) +(defvar vm-folder-directory) +(defvar w3m-current-url) +(defvar w3m-current-title) +(declare-function wl-summary-buffer-msgdb "ext:wl-folder" (&rest unknown) t) +(declare-function wl-folder-get-elmo-folder "ext:wl-folder" (entity &optional no-cache)) +(declare-function wl-summary-goto-folder-subr "ext:wl-summary" (&optional name scan-type other-window sticky interactive scoring force-exit)) +(declare-function wl-summary-jump-to-msg-by-message-id "ext:wl-summary" (&optional id)) +(declare-function wl-summary-line-from "ext:wl-summary" ()) +(declare-function wl-summary-line-subject "ext:wl-summary" ()) +(declare-function wl-summary-message-number "ext:wl-summary" ()) +(declare-function wl-summary-redisplay "ext:wl-summary" (&optional arg)) +(defvar wl-summary-buffer-elmo-folder) +(defvar wl-summary-buffer-folder-name) +(declare-function speedbar-line-directory "speedbar" (&optional depth)) + +(defvar org-latex-regexps) +(defvar constants-unit-system) + ;;; Variables for pre-computed regular expressions, all buffer local (defvar org-drawer-regexp nil @@ -4452,49 +4594,6 @@ Respect keys that are already there." "Function to be called when `C-c C-c' is used. This is for getting out of special buffers like remember.") -;;; Foreign variables, to inform the compiler - -;; XEmacs only -(defvar outline-mode-menu-heading) -(defvar outline-mode-menu-show) -(defvar outline-mode-menu-hide) -(defvar zmacs-regions) ; XEmacs regions -;; Emacs only -(defvar mark-active) - -;; Packages that org-mode interacts with -(defvar calc-embedded-close-formula) -(defvar calc-embedded-open-formula) -(defvar font-lock-unfontify-region-function) -(defvar org-goto-start-pos) -(defvar vm-message-pointer) -(defvar vm-folder-directory) -(defvar wl-summary-buffer-elmo-folder) -(defvar wl-summary-buffer-folder-name) -(defvar gnus-other-frame-object) -(defvar gnus-group-name) -(defvar gnus-article-current) -(defvar w3m-current-url) -(defvar w3m-current-title) -(defvar mh-progs) -(defvar mh-current-folder) -(defvar mh-show-folder-buffer) -(defvar mh-index-folder) -(defvar mh-searcher) -(defvar calendar-mode-map) -(defvar Info-current-file) -(defvar Info-current-node) -(defvar texmathp-why) -(defvar remember-save-after-remembering) -(defvar remember-data-file) -(defvar remember-register) -(defvar remember-buffer) -(defvar annotation) ; from remember.el, dynamically scoped in `remember-mode' -(defvar initial) ; from remember.el, dynamically scoped in `remember-mode' -(defvar org-latex-regexps) -(defvar constants-unit-system) - -(defvar original-date) ; dynamically scoped in calendar.el does scope this ;; FIXME: Occasionally check by commenting these, to make sure ;; no other functions uses these, forgetting to let-bind them. @@ -5142,7 +5241,7 @@ We use a macro so that the test can happen at compilation time." (re-macros (if org-export-with-TeX-macros (list (concat "\\\\" - (regexp-opt + (regexp-opt (append (mapcar 'car org-html-entities) (if (boundp 'org-latex-entities) org-latex-entities nil)) @@ -5712,6 +5811,8 @@ RET=jump to location [Q]uit and return to previous location \[Up]/[Down]=next/prev headline TAB=cycle visibility [/] org-occur" ) +(defvar org-goto-start-pos) ; dynamically scoped parameter + (defun org-goto () "Look up a different location in the current file, keeping current visibility. @@ -6188,36 +6289,56 @@ is signaled in this case." 'outline-get-last-sibling)) (ins-point (make-marker)) (cnt (abs arg)) - beg end txt folded) + beg beg0 end txt folded ne-beg ne-end ne-ins ins-end) ;; Select the tree (org-back-to-heading) - (setq beg (point)) + (setq beg0 (point)) + (save-excursion + (setq ne-beg (org-back-over-empty-lines)) + (setq beg (point))) (save-match-data (save-excursion (outline-end-of-heading) (setq folded (org-invisible-p))) (outline-end-of-subtree)) (outline-next-heading) + (setq ne-end (org-back-over-empty-lines)) (setq end (point)) + (goto-char beg0) + (when (and (> arg 0) (org-first-sibling-p) (< ne-end ne-beg)) + ;; include less whitespace + (save-excursion + (goto-char beg) + (forward-line (- ne-beg ne-end)) + (setq beg (point)))) ;; Find insertion point, with error handling - (goto-char beg) (while (> cnt 0) (or (and (funcall movfunc) (looking-at outline-regexp)) - (progn (goto-char beg) + (progn (goto-char beg0) (error "Cannot move past superior level or buffer limit"))) (setq cnt (1- cnt))) (if (> arg 0) ;; Moving forward - still need to move over subtree (progn (outline-end-of-subtree) - (outline-next-heading) - (if (not (or (looking-at (concat "^" outline-regexp)) - (bolp))) - (newline)))) + (org-back-over-empty-lines) + (or (bolp) (newline)))) + (setq ne-ins (org-back-over-empty-lines)) (move-marker ins-point (point)) (setq txt (buffer-substring beg end)) (delete-region beg end) (insert txt) (or (bolp) (insert "\n")) + (setq ins-end (point)) (goto-char ins-point) + (org-skip-whitespace) + (when (and (< arg 0) + (org-first-sibling-p) + (> ne-ins ne-beg)) + ;; Move whitespace back to beginning + (save-excursion + (goto-char ins-end) + (let ((kill-whole-line t)) + (kill-line (- ne-ins ne-beg)) (point))) + (insert (make-string (- ne-ins ne-beg) ?\n))) (if folded (hide-subtree)) (move-marker ins-point nil))) @@ -6247,7 +6368,9 @@ If CUT is non-nil, actually cut the subtree." (if (interactive-p) (org-back-to-heading nil) ; take what looks like a subtree (org-back-to-heading t)) ; take what is really there + (org-back-over-empty-lines) (setq beg (point)) + (skip-chars-forward " \t\r\n") (save-match-data (save-excursion (outline-end-of-heading) (setq folded (org-invisible-p))) @@ -6255,6 +6378,7 @@ If CUT is non-nil, actually cut the subtree." (outline-forward-same-level (1- n)) (error nil)) (org-end-of-subtree t t)) + (org-back-over-empty-lines) (setq end (point)) (goto-char beg) (when (> end beg) @@ -6284,7 +6408,7 @@ If you want to insert the tree as is, just use \\[yank]. If optional TREE is given, use this text instead of the kill ring." (interactive "P") (unless (org-kill-is-subtree-p tree) - (error + (error "%s" (substitute-command-keys "The kill is not a (set of) tree(s) - please use \\[yank] to yank anyway"))) (let* ((txt (or tree (and kill-ring (current-kill 0)))) @@ -6337,6 +6461,8 @@ If optional TREE is given, use this text instead of the kill ring." (unless (string-match "\n\\'" txt) (insert "\n")) (setq end (point)) (goto-char beg) + (skip-chars-forward " \t\n\r") + (setq beg (point)) ;; Shift if necessary (unless (= shift 0) (save-restriction @@ -6362,10 +6488,12 @@ which is OK for `org-paste-subtree'. If optional TXT is given, check this string instead of the current kill." (let* ((kill (or txt (and kill-ring (current-kill 0)) "")) (start-level (and kill - (string-match (concat "\\`" org-outline-regexp) kill) - (- (match-end 0) (match-beginning 0) 1))) + (string-match (concat "\\`\\([ \t\n\r]*?\n\\)?\\(" + org-outline-regexp "\\)") + kill) + (- (match-end 2) (match-beginning 2) 1))) (re (concat "^" org-outline-regexp)) - (start 1)) + (start (1+ (match-beginning 2)))) (if (not start-level) (progn nil) ;; does not even start with a heading @@ -6921,22 +7049,37 @@ Error if not at a plain list, or if this is the first item in the list." Subitems (items with larger indentation) are considered part of the item, so this really moves item trees." (interactive) - (let (beg end ind ind1 (pos (point)) txt) + (let (beg beg0 end end0 ind ind1 (pos (point)) txt ne-end ne-beg) (org-beginning-of-item) - (setq beg (point)) + (setq beg0 (point)) + (save-excursion + (setq ne-beg (org-back-over-empty-lines)) + (setq beg (point))) + (goto-char beg0) (setq ind (org-get-indentation)) (org-end-of-item) - (setq end (point)) + (setq end0 (point)) (setq ind1 (org-get-indentation)) + (setq ne-end (org-back-over-empty-lines)) + (setq end (point)) + (goto-char beg0) + (when (and (org-first-list-item-p) (< ne-end ne-beg)) + ;; include less whitespace + (save-excursion + (goto-char beg) + (forward-line (- ne-beg ne-end)) + (setq beg (point)))) + (goto-char end0) (if (and (org-at-item-p) (= ind ind1)) (progn (org-end-of-item) + (org-back-over-empty-lines) (setq txt (buffer-substring beg end)) (save-excursion (delete-region beg end)) (setq pos (point)) (insert txt) - (goto-char pos) + (goto-char pos) (org-skip-whitespace) (org-maybe-renumber-ordered-list)) (goto-char pos) (error "Cannot move this item further down")))) @@ -6946,13 +7089,19 @@ so this really moves item trees." Subitems (items with larger indentation) are considered part of the item, so this really moves item trees." (interactive "p") - (let (beg end ind ind1 (pos (point)) txt) + (let (beg beg0 end end0 ind ind1 (pos (point)) txt + ne-beg ne-end ne-ins ins-end) (org-beginning-of-item) - (setq beg (point)) + (setq beg0 (point)) (setq ind (org-get-indentation)) + (save-excursion + (setq ne-beg (org-back-over-empty-lines)) + (setq beg (point))) + (goto-char beg0) (org-end-of-item) + (setq ne-end (org-back-over-empty-lines)) (setq end (point)) - (goto-char beg) + (goto-char beg0) (catch 'exit (while t (beginning-of-line 0) @@ -6971,12 +7120,23 @@ so this really moves item trees." (setq ind1 (org-get-indentation)) (if (and (org-at-item-p) (= ind ind1)) (progn + (setq ne-ins (org-back-over-empty-lines)) (setq txt (buffer-substring beg end)) (save-excursion (delete-region beg end)) (setq pos (point)) (insert txt) - (goto-char pos) + (setq ins-end (point)) + (goto-char pos) (org-skip-whitespace) + + (when (and (org-first-list-item-p) (> ne-ins ne-beg)) + ;; Move whitespace back to beginning + (save-excursion + (goto-char ins-end) + (let ((kill-whole-line t)) + (kill-line (- ne-ins ne-beg)) (point))) + (insert (make-string (- ne-ins ne-beg) ?\n))) + (org-maybe-renumber-ordered-list)) (goto-char pos) (error "Cannot move this item further up")))) @@ -7697,8 +7857,8 @@ When TAG is non-nil, don't move trees, but mark them with the ARCHIVE tag." (org-hide-archived-subtrees beg end) (goto-char beg) (if (looking-at (concat ".*:" org-archive-tag ":")) - (message (substitute-command-keys - "Subtree is archived and stays closed. Use \\[org-force-cycle-archived] to cycle it anyway."))))))) + (message "%s" (substitute-command-keys + "Subtree is archived and stays closed. Use \\[org-force-cycle-archived] to cycle it anyway."))))))) (defun org-force-cycle-archived () "Cycle subtree even if it is archived." @@ -8868,7 +9028,8 @@ should be done in reverse order." (skip-chars-backward "^|") (setq ecol (1- (current-column))) (org-table-goto-column column) - (setq lns (mapcar (lambda(x) (cons (org-trim (substring x bcol ecol)) x)) + (setq lns (mapcar (lambda(x) (cons (org-sort-remove-invisible + (org-trim (substring x bcol ecol))) x)) (org-split-string (buffer-substring beg end) "\n"))) (setq lns (org-do-sort lns "Table" with-case sorting-type)) (delete-region beg end) @@ -8879,6 +9040,14 @@ should be done in reverse order." (org-table-goto-column thiscol) (message "%d lines sorted, based on column %d" (length lns) column))) +;; FIXME: maybe we will not need this? Table sorting is broken.... +(defun org-sort-remove-invisible (s) + (remove-text-properties 0 (length s) org-rm-props s) + (if (string-match org-bracket-link-regexp s) + (setq s (replace-match (if (match-end 2) (match-string 3 s) + (match-string 1 s))))) + s) + (defun org-table-cut-region (beg end) "Copy region in table to the clipboard and blank all relevant fields." (interactive "r") @@ -9581,7 +9750,7 @@ of the new mark." (goto-line l1))) (if (not (= epos (point-at-eol))) (org-table-align)) (goto-line l) - (and (interactive-p) (message (cdr (assoc new org-recalc-marks)))))) + (and (interactive-p) (message "%s" (cdr (assoc new org-recalc-marks)))))) (defun org-table-maybe-recalculate-line () "Recompute the current line if marked for it, and if we haven't just done it." @@ -12194,7 +12363,7 @@ optional argument IN-EMACS is non-nil, Emacs will visit the file." (setq type (match-string 1 link) path (match-string 2 link)) (setq type "thisfile" path link)) (throw 'match t))) - + (when (get-text-property (point) 'org-linked-text) (setq type "thisfile" pos (if (get-text-property (1+ (point)) 'org-linked-text) @@ -12203,7 +12372,7 @@ optional argument IN-EMACS is non-nil, Emacs will visit the file." (previous-single-property-change pos 'org-linked-text) (next-single-property-change pos 'org-linked-text))) (throw 'match t)) - + (save-excursion (when (or (org-in-regexp org-angle-link-re) (org-in-regexp org-plain-link-re)) @@ -12225,12 +12394,12 @@ optional argument IN-EMACS is non-nil, Emacs will visit the file." ;; Remove any trailing spaces in path (if (string-match " +\\'" path) (setq path (replace-match "" t t path))) - + (cond - + ((assoc type org-link-protocols) (funcall (nth 1 (assoc type org-link-protocols)) path)) - + ((equal type "mailto") (let ((cmd (car org-link-mailto-program)) (args (cdr org-link-mailto-program)) args1 @@ -12248,11 +12417,11 @@ optional argument IN-EMACS is non-nil, Emacs will visit the file." (setq a (replace-match subject t t a))) (push a args1)))) (apply cmd (nreverse args1)))) - + ((member type '("http" "https" "ftp" "news")) (browse-url (concat type ":" (org-link-escape path org-link-escape-chars-browser)))) - + ((string= type "tags") (org-tags-view in-emacs path)) ((string= type "thisfile") @@ -12268,10 +12437,10 @@ optional argument IN-EMACS is non-nil, Emacs will visit the file." ,pos))) (condition-case nil (eval cmd) (error (progn (widen) (eval cmd)))))) - + ((string= type "tree-match") (org-occur (concat "\\[" (regexp-quote path) "\\]"))) - + ((string= type "file") (if (string-match "::\\([0-9]+\\)\\'" path) (setq line (string-to-number (match-string 1 path)) @@ -12282,16 +12451,16 @@ optional argument IN-EMACS is non-nil, Emacs will visit the file." (if (string-match "[*?{]" (file-name-nondirectory path)) (dired path) (org-open-file path in-emacs line search))) - + ((string= type "news") (org-follow-gnus-link path)) - + ((string= type "bbdb") (org-follow-bbdb-link path)) - + ((string= type "info") (org-follow-info-link path)) - + ((string= type "gnus") (let (group article) (if (not (string-match "\\`\\([^#]+\\)\\(#\\(.*\\)\\)?" path)) @@ -12299,7 +12468,7 @@ optional argument IN-EMACS is non-nil, Emacs will visit the file." (setq group (match-string 1 path) article (match-string 3 path)) (org-follow-gnus-link group article))) - + ((string= type "vm") (let (folder article) (if (not (string-match "\\`\\([^#]+\\)\\(#\\(.*\\)\\)?" path)) @@ -12308,7 +12477,7 @@ optional argument IN-EMACS is non-nil, Emacs will visit the file." article (match-string 3 path)) ;; in-emacs is the prefix arg, will be interpreted as read-only (org-follow-vm-link folder article in-emacs))) - + ((string= type "wl") (let (folder article) (if (not (string-match "\\`\\([^#]+\\)\\(#\\(.*\\)\\)?" path)) @@ -12316,7 +12485,7 @@ optional argument IN-EMACS is non-nil, Emacs will visit the file." (setq folder (match-string 1 path) article (match-string 3 path)) (org-follow-wl-link folder article))) - + ((string= type "mhe") (let (folder article) (if (not (string-match "\\`\\([^#]+\\)\\(#\\(.*\\)\\)?" path)) @@ -12324,7 +12493,7 @@ optional argument IN-EMACS is non-nil, Emacs will visit the file." (setq folder (match-string 1 path) article (match-string 3 path)) (org-follow-mhe-link folder article))) - + ((string= type "rmail") (let (folder article) (if (not (string-match "\\`\\([^#]+\\)\\(#\\(.*\\)\\)?" path)) @@ -12332,7 +12501,7 @@ optional argument IN-EMACS is non-nil, Emacs will visit the file." (setq folder (match-string 1 path) article (match-string 3 path)) (org-follow-rmail-link folder article))) - + ((string= type "shell") (let ((cmd path)) (if (or (not org-confirm-shell-link-function) @@ -12344,7 +12513,7 @@ optional argument IN-EMACS is non-nil, Emacs will visit the file." (message "Executing %s" cmd) (shell-command cmd)) (error "Abort")))) - + ((string= type "elisp") (let ((cmd path)) (if (or (not org-confirm-elisp-link-function) @@ -12354,7 +12523,7 @@ optional argument IN-EMACS is non-nil, Emacs will visit the file." 'face 'org-warning)))) (message "%s => %s" cmd (eval (read cmd))) (error "Abort")))) - + (t (browse-url-at-point))))) (move-marker org-open-link-marker nil))) @@ -12566,7 +12735,7 @@ to read." (move-marker (car org-mark-ring) (or pos (point)) (or buffer (current-buffer))) - (message + (message "%s" (substitute-command-keys "Position saved to mark ring, go back with \\[org-mark-ring-goto]."))) @@ -12648,7 +12817,7 @@ onto the ring." (if (match-string 2 name) ; If there isn't a node, choose "Top" (Info-find-node (match-string 1 name) (match-string 2 name)) (Info-find-node (match-string 1 name) "Top"))) - (message (concat "Could not open: " name)))) + (message "Could not open: %s" name))) (defun org-follow-gnus-link (&optional group article) "Follow a Gnus link to GROUP and ARTICLE." @@ -12772,7 +12941,7 @@ sequences, it will now work." (save-excursion (mh-index-previous-folder) (re-search-forward "^\\(+.*\\)$" nil t) - (message (match-string 1)))) + (message "%s" (match-string 1)))) (defun org-mhe-get-message-folder () "Return the name of the current message folder. Be careful if you @@ -12992,6 +13161,9 @@ on the system \"/user@host:\"." ;;;; Hooks for remember.el, and refiling +(defvar annotation) ; from remember.el, dynamically scoped in `remember-mode' +(defvar initial) ; from remember.el, dynamically scoped in `remember-mode' + ;;;###autoload (defun org-remember-insinuate () "Setup remember.el for use wiht Org-mode." @@ -13094,7 +13266,8 @@ to be run from that hook to function properly." v-a)) (v-n user-full-name) (org-startup-folded nil) - org-time-was-given org-end-time-was-given x prompt char time pos) + org-time-was-given org-end-time-was-given x + prompt completions char time pos default histvar) (setq org-store-link-plist (append (list :annotation v-a :initial v-i) org-store-link-plist)) @@ -13126,7 +13299,7 @@ to be run from that hook to function properly." (replace-match (or (eval (intern (concat "v-" (match-string 1)))) "") t t)) - + ;; %[] Insert contents of a file. (goto-char (point-min)) (while (re-search-forward "%\\[\\(.+\\)\\]" nil t) @@ -13174,6 +13347,15 @@ to be run from that hook to function properly." prompt (if (match-end 2) (match-string 2))) (goto-char (match-beginning 0)) (replace-match "") + (setq completions nil default nil) + (when prompt + (setq completions (org-split-string prompt "|") + prompt (pop completions) + default (car completions) + histvar (intern (concat + "org-remember-template-prompt-history::" + (or prompt ""))) + completions (mapcar 'list completions))) (cond ((member char '("G" "g")) (let* ((org-last-tags-completion-table @@ -13199,14 +13381,31 @@ to be run from that hook to function properly." (member char '("u" "U")) nil nil (list org-end-time-was-given))) (t - (insert (read-string - (if prompt (concat prompt ": ") "Enter string")))))) + (insert (completing-read + (concat (if prompt prompt "Enter string") + (if default (concat " [" default "]")) + ": ") + completions nil nil nil histvar default))))) (goto-char (point-min)) (if (re-search-forward "%\\?" nil t) (replace-match "") (and (re-search-forward "^[^#\n]" nil t) (backward-char 1)))) (org-mode) - (org-set-local 'org-finish-function 'remember-finalize))) + (org-set-local 'org-finish-function 'remember-finalize)) + (when (save-excursion + (goto-char (point-min)) + (re-search-forward "%!" nil t)) + (replace-match "") + (add-hook 'post-command-hook 'org-remember-finish-immediately 'append))) + +(defun org-remember-finish-immediately () + "File remember note immediately. +This should be run in `post-command-hook' and will remove itself +from that hook." + (remove-hook 'post-command-hook 'org-remember-finish-immediately) + (when org-finish-function + (funcall org-finish-function))) + ;;;###autoload (defun org-remember (&optional goto org-force-remember-template-char) @@ -13216,13 +13415,16 @@ of the remember buffer. When called interactively with a `C-u' prefix argument GOTO, don't remember anything, just go to the file/headline where the selected templated usually -stores its notes. +stores its notes. With a double prefix arg `C-u C-u', got to the last +note stored by remember. Lisp programs can set ORG-FORCE-REMEMBER-TEMPLATE-CHAR to a character associated with a template in `org-remember-tempates'." (interactive "P") - (if (equal goto '(4)) - (org-go-to-remember-target) + (cond + ((equal goto '(4)) (org-go-to-remember-target)) + ((equal goto '(16)) (org-remember-goto-last-stored)) + (t (if (eq org-finish-function 'remember-buffer) (progn (when (< (length org-remember-templates) 2) @@ -13234,7 +13436,13 @@ associated with a template in `org-remember-tempates'." (message "Press C-c C-c to remember data")) (if (org-region-active-p) (remember (buffer-substring (point) (mark))) - (call-interactively 'remember))))) + (call-interactively 'remember)))))) + +(defun org-remember-goto-last-stored () + "Go to the location where the last remember note was stored." + (interactive) + (bookmark-jump "org-remember-last-stored") + (message "This is the last note stored by remember")) (defun org-go-to-remember-target (&optional template-key) "Go to the target location of a remember template. @@ -13397,13 +13605,16 @@ See also the variable `org-reverse-note-order'." (beginning-of-line 2) (end-of-line 1) (insert "\n")))) + (bookmark-set "org-remember-last-stored") (org-paste-subtree (org-get-legal-level level 1) txt)) ((eq exitcmd 'left) ;; before current + (bookmark-set "org-remember-last-stored") (org-paste-subtree level txt)) ((eq exitcmd 'right) ;; after current (org-end-of-subtree t) + (bookmark-set "org-remember-last-stored") (org-paste-subtree level txt)) (t (error "This should not happen")))) @@ -13413,6 +13624,7 @@ See also the variable `org-reverse-note-order'." (widen) (goto-char (point-max)) (if (not (bolp)) (newline)) + (bookmark-set "org-remember-last-stored") (org-paste-subtree (org-get-legal-level 1 1) txt))) ((and (bobp) reversed) @@ -13422,10 +13634,12 @@ See also the variable `org-reverse-note-order'." (goto-char (point-min)) (re-search-forward "^\\*+ " nil t) (beginning-of-line 1) + (bookmark-set "org-remember-last-stored") (org-paste-subtree 1 txt))) (t ;; Put it right there, with automatic level determined by ;; org-paste-subtree or from prefix arg + (bookmark-set "org-remember-last-stored") (org-paste-subtree (if (numberp current-prefix-arg) current-prefix-arg) txt))) @@ -13491,6 +13705,12 @@ See also the variable `org-reverse-note-order'." (1- (* 2 (cdr desc))) (cdr desc))) "\\}[ \t]"))) + ((eq (car desc) :maxlevel) + (setq descre (concat "^\\*\\{1," (number-to-string + (if org-odd-levels-only + (1- (* 2 (cdr desc))) + (cdr desc))) + "\\}[ \t]"))) (t (error "Bad refiling target description %s" desc))) (while (setq f (pop files)) (save-excursion @@ -13511,11 +13731,24 @@ See also the variable `org-reverse-note-order'." (regexp-quote (match-string 5))))) (setq re (concat re "[ \t]*$")) + (when org-refile-use-outline-path + (setq txt (mapconcat 'identity + (append (org-get-outline-path) + (list txt)) + "/"))) (push (list txt f re (point)) targets)) (goto-char (point-at-eol)))))))) (org-release-buffers org-agenda-new-buffers) (nreverse targets))) +(defun org-get-outline-path () + (let (rtn) + (save-excursion + (while (org-up-heading-safe) + (when (looking-at org-complex-heading-regexp) + (push (org-match-string-no-properties 4) rtn))) + rtn))) + (defun org-refile (&optional reversed-or-update) "Move the entry at point to another heading. The list of target headings is compiled using the information in @@ -14102,8 +14335,6 @@ Returns the new TODO keyword, or nil if no state change should occur." (save-window-excursion (if expert (set-buffer (get-buffer-create " *Org todo*")) -; (delete-other-windows) -; (split-window-vertically) (org-switch-to-buffer-other-window (get-buffer-create " *Org todo*"))) (erase-buffer) (org-set-local 'org-done-keywords done-keywords) @@ -14196,7 +14427,7 @@ This function should be run in the `org-after-todo-state-change-hook'." (org-timestamp-change n (cdr (assoc what whata)))) (setq msg (concat msg type org-last-changed-timestamp " "))) (setq org-log-post-message msg) - (message msg)))) + (message "%s" msg)))) (defun org-show-todo-tree (arg) "Make a compact tree which shows all headlines marked with TODO. @@ -14415,7 +14646,7 @@ The auto-repeater uses this.") (with-current-buffer (marker-buffer 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))) + (and org-log-post-message (message "%s" org-log-post-message))) ;; FIXME: what else would be useful? ;; - priority @@ -14430,14 +14661,17 @@ t Show entries with a specific TODO keyword. T Show entries selected by a tags match. p Enter a property name and its value (both with completion on existing names/values) and show entries with that property. -r Show entries matching a regular expression" +r Show entries matching a regular expression +d Show deadlines due within `org-deadline-warning-days'." (interactive "P") (let (ans kwd value) - (message "Sparse tree: [/]regexp [t]odo-kwd [T]ag [p]roperty [d]eadlines") + (message "Sparse tree: [/]regexp [t]odo-kwd [T]ag [p]roperty [d]eadlines [b]efore-date") (setq ans (read-char-exclusive)) (cond ((equal ans ?d) (call-interactively 'org-check-deadlines)) + ((equal ans ?b) + (call-interactively 'org-check-before-date)) ((equal ans ?t) (org-show-todo-tree '(4))) ((equal ans ?T) @@ -15670,10 +15904,10 @@ in the current file." (let* ((prop (completing-read "Property: " (org-entry-properties nil 'standard)))) (list prop))) - (message (concat "Property " property - (if (org-entry-delete nil property) - " deleted" - " was not present in the entry")))) + (message "Property %s %s" property + (if (org-entry-delete nil property) + "deleted" + "was not present in the entry"))) (defun org-delete-property-globally (property) "Remove PROPERTY globally, from all entries." @@ -17372,6 +17606,20 @@ days. If the prefix is a raw \\[universal-argument] prefix, all deadlines are s (org-occur regexp nil callback) org-warn-days))) +(defun org-check-before-date (date) + "Check if there are deadlines or scheduled entries before DATE." + (interactive (list (org-read-date))) + (let ((case-fold-search nil) + (regexp (concat "\\<\\(" org-deadline-string + "\\|" org-scheduled-string + "\\) *<\\([^>]+\\)>")) + (callback + (lambda () (time-less-p + (org-time-string-to-time (match-string 2)) + (org-time-string-to-time date))))) + (message "%d entries before %s" + (org-occur regexp nil callback) date))) + (defun org-evaluate-time-range (&optional to-buffer) "Evaluate a time range by computing the difference between start and end. Normally the result is just printed in the echo area, but with prefix arg @@ -17419,7 +17667,7 @@ days in order to avoid rounding problems." d (floor (+ (/ diff ds) 0.5)) h 0 m 0)) (if (not to-buffer) - (message (org-make-tdiff-string y d h m)) + (message "%s" (org-make-tdiff-string y d h m)) (if (org-at-table-p) (progn (goto-char match-end) @@ -18936,6 +19184,16 @@ Pressing `<' twice means to restrict to the current subtree or region ((equal keys "!") (customize-variable 'org-stuck-projects)) (t (error "Invalid agenda key")))))) +(defun org-agenda-normalize-custom-commands (cmds) + (delq nil + (mapcar + (lambda (x) + (cond ((stringp (cdr x)) nil) + ((stringp (nth 1 x)) x) + ((not (nth 1 x)) (cons (car x) (cons "" (cddr x)))) + (t (cons (car x) (cons "" (cdr x)))))) + cmds))) + (defun org-agenda-get-restriction-and-command (prefix-descriptions) "The user interface for selecting an agenda command." (catch 'exit @@ -19256,7 +19514,7 @@ so the the export commands caneasily use it." ;;;###autoload (defmacro org-batch-store-agenda-views (&rest parameters) "Run all custom agenda commands that have a file argument." - (let ((cmds org-agenda-custom-commands) + (let ((cmds (org-agenda-normalize-custom-commands org-agenda-custom-commands)) (pop-up-frames nil) (dir default-directory) pars cmd thiscmdkey files opts) @@ -19267,8 +19525,8 @@ so the the export commands caneasily use it." (while cmds (setq cmd (pop cmds) thiscmdkey (car cmd) - opts (nth 3 cmd) - files (nth 4 cmd)) + opts (nth 4 cmd) + files (nth 5 cmd)) (if (stringp files) (setq files (list files))) (when files (eval (list 'let (append org-agenda-exporter-settings opts pars) @@ -19388,8 +19646,8 @@ the buffer and restores the previous window configuration." (org-install-agenda-files-menu) (message "New agenda file list installed")) nil 'local) - (message (substitute-command-keys - "Edit list and finish with \\[save-buffer]"))) + (message "%s" (substitute-command-keys + "Edit list and finish with \\[save-buffer]"))) (customize-variable 'org-agenda-files))) (defun org-store-new-agenda-file-list (list) @@ -24440,7 +24698,8 @@ lang=\"%s\" xml:lang=\"%s\"> (replace-match "\\2\n")) (insert line "\n") (while (and lines - (get-text-property 0 'org-protected (car lines))) + (or (= (length (car lines)) 0) + (get-text-property 0 'org-protected (car lines)))) (insert (pop lines) "\n")) (and par (insert "

\n"))) (throw 'nextline nil)) @@ -25815,6 +26074,7 @@ The XOXO buffer is named *xoxo-*" (org-defkey org-mode-map "\C-c\C-k" 'org-kill-note-or-show-branches) (org-defkey org-mode-map "\C-c#" 'org-update-checkbox-count) (org-defkey org-mode-map "\C-m" 'org-return) +(org-defkey org-mode-map "\C-j" 'org-return-indent) (org-defkey org-mode-map "\C-c?" 'org-table-field-info) (org-defkey org-mode-map "\C-c " 'org-table-blank-field) (org-defkey org-mode-map "\C-c+" 'org-table-sum) @@ -26283,18 +26543,24 @@ Also updates the keyword regular expressions." (let ((org-note-abort t)) (funcall org-finish-function)))) -(defun org-return () +(defun org-return (&optional indent) "Goto next table row or insert a newline. Calls `org-table-next-row' or `newline', depending on context. See the individual commands for more information." (interactive) (cond - ((bobp) (newline)) + ((bobp) (if indent (newline-and-indent) (newline))) ((org-at-table-p) (org-table-justify-field-maybe) (call-interactively 'org-table-next-row)) - (t (newline)))) + (t (if indent (newline-and-indent) (newline))))) +(defun org-return-indent () + (interactive) + "Goto next table row or insert a newline and indent. +Calls `org-table-next-row' or `newline-and-indent', depending on +context. See the individual commands for more information." + (org-return t)) (defun org-ctrl-c-minus () "Insert separator line in table or modify bullet type in list. @@ -26758,6 +27024,17 @@ really on, so that the block visually is on the match." (setq list (delete (pop elts) list))) list) +(defun org-back-over-empty-lines () + "Move backwards over witespace, to the beginning of the first empty line. +Returns the number o empty lines passed." + (let ((pos (point))) + (skip-chars-backward " \t\n\r") + (beginning-of-line 2) + (count-lines (point) pos))) + +(defun org-skip-whitespace () + (skip-chars-forward " \t\n\r")) + (defun org-point-in-group (point group &optional context) "Check if POINT is in match-group GROUP. If CONTEXT is non-nil, return a list with CONTEXT and the boundaries of the @@ -27101,6 +27378,20 @@ headline found, or nil if no higher level is found." (if (< level start-level) (throw 'exit level))) nil))) +(defun org-first-sibling-p () + "Is this heading the first child of its parents?" + (interactive) + (let ((re (concat "^" outline-regexp)) + level l) + (unless (org-at-heading-p t) + (error "Not at a heading")) + (setq level (funcall outline-level)) + (save-excursion + (if (not (re-search-backward re nil t)) + t + (setq l (funcall outline-level)) + (< l level))))) + (defun org-goto-sibling (&optional previous) "Goto the next sibling, even if it is invisible. When PREVIOUS is set, go to the previous sibling instead. Returns t @@ -27275,7 +27566,7 @@ Show the heading too, if it is currently invisible." '(progn (add-hook 'imenu-after-jump-hook (lambda () (org-show-context 'org-goto))))) - + ;; Speedbar support (defun org-speedbar-set-agenda-restriction () @@ -27385,6 +27676,13 @@ Still experimental, may disappear in the future." ;; make tree, check each match with the callback (org-occur "CLOSED: +\\[\\(.*?\\)\\]" nil callback))) +(defun org-first-list-item-p () + "Is this heading the item in a plain list?" + (unless (org-at-item-p) + (error "Not at a plain list item")) + (org-beginning-of-item) + (= (point) (save-excursion (org-beginning-of-item-list)))) + ;;;; Finish up (provide 'org) diff --git a/org.pdf b/org.pdf index aa2086cfa..aa247ad8d 100644 Binary files a/org.pdf and b/org.pdf differ diff --git a/org.texi b/org.texi index 8b0fa69fc..523b51ee8 100644 --- a/org.texi +++ b/org.texi @@ -3,7 +3,7 @@ @setfilename ../../info/org @settitle Org Mode Manual -@set VERSION 5.16a +@set VERSION 5.17 @set DATE December 2007 @dircategory Emacs @@ -91,7 +91,7 @@ Software Foundation raise funds for GNU development.'' * Miscellaneous:: All the rest which did not fit elsewhere * Extensions and Hacking:: It is possible to write add-on code * History and Acknowledgments:: How Org-mode came into being -* Main Index:: +* Index:: The index * Key Index:: Key bindings and where they are described @detailmenu @@ -169,10 +169,10 @@ TODO items Extended use of TODO keywords * Workflow states:: From TODO to DONE in steps -* TODO types:: I do this, Fred the rest +* TODO types:: I do this, Fred does the rest * Multiple sets in one file:: Mixing it all, and still finding your way * Fast access to TODO states:: Single letter selection of a state -* Per file keywords:: Different files, different requirements +* Per-file keywords:: Different files, different requirements * Faces for TODO keywords:: Highlighting states Progress Logging @@ -594,23 +594,22 @@ attach it to your bug report. @node Conventions, , Feedback, Introduction @section Typesetting conventions used in this manual -Org-mode has 3 types of keywords that are being used. TODO keywords, -tags, and property names. For this manual we are using the following -conventions: +Org-mode uses three types of keywords: TODO keywords, tags, and property +names. In this manual we use the following conventions: @table @code @item TODO @itemx WAITING -TODO keyword are written with all capitals, even if they are +TODO keywords are written with all capitals, even if they are user-defined. @item boss @itemx ARCHIVE -User-defined Tags are written in lowercase, built-in tags with special -meaning a all-caps. +User-defined tags are written in lowercase; built-in tags with special +meaning are written with all capitals. @item Release @itemx PRIORITY -User-defined properties are capitalized in all examples, while -built-in properties with special meaning are all-caps. +User-defined properties are capitalized; built-in properties with +special meaning are written with all capitals. @end table @node Document structure, Tables, Introduction, Top @@ -740,8 +739,10 @@ Show all. @item C-c C-r Reveal context around point, showing the current entry, the following heading and the hierarchy above. Useful for working near a location -exposed by a sparse tree command (@pxref{Sparse trees}) or an agenda -command (@pxref{Agenda commands}). With prefix arg show, on each +that has been exposed by a sparse tree command (@pxref{Sparse trees}) or +an agenda command (@pxref{Agenda commands}). With prefix arg show, on +each + level, all sibling headings. @kindex C-c C-x b @item C-c C-x b @@ -1022,14 +1023,13 @@ location as the value (@pxref{Properties and columns}). @cindex occur, command An important feature of Org-mode is the ability to construct -@emph{sparse trees} for selected information in an outline tree. A -sparse tree means that the entire document is folded as much as -possible, but the selected information is made visible along with the -headline structure above it@footnote{See also the variables -@code{org-show-hierarchy-above}, @code{org-show-following-heading}, and -@code{org-show-siblings} for detailed control on how much context is -shown around each match.}. Just try it out and you will see immediately -how it works. +@emph{sparse trees} for selected information in an outline tree, so that +the entire document is folded as much as possible, but the selected +information is made visible along with the headline structure above +it@footnote{See also the variables @code{org-show-hierarchy-above}, +@code{org-show-following-heading}, and @code{org-show-siblings} for +detailed control on how much context is shown around each match.}. Just +try it out and you will see immediately how it works. Org-mode contains several commands creating such trees, all these commands can be accessed through a dispatcher: @@ -1050,6 +1050,7 @@ when the buffer is changed by an editing command, or by pressing @kbd{C-c C-c}. When called with a @kbd{C-u} prefix argument, previous highlights are kept, so several calls to this command can be stacked. @end table + @noindent For frequently used sparse trees of specific search strings, you can use the variable @code{org-agenda-custom-commands} to define fast @@ -1088,7 +1089,7 @@ part of the document and print the resulting file. Within an entry of the outline tree, hand-formatted lists can provide additional structure. They also provide a way to create lists of checkboxes (@pxref{Checkboxes}). Org-mode supports editing such lists, -and the HTML exporter (@pxref{Exporting}) does parse and format them. +and the HTML exporter (@pxref{Exporting}) parses and formats them. Org-mode knows ordered and unordered lists. Unordered list items start with @samp{-}, @samp{+}, or @samp{*}@footnote{When using @samp{*} as a @@ -1096,8 +1097,9 @@ bullet, lines must be indented or they will be seen as top-level headlines. Also, when you are hiding leading stars to get a clean outline view, plain list items starting with a star are visually indistinguishable from true headlines. In short: even though @samp{*} -is supported, it may be better not to use it for plain list items.} as -bullets. Ordered list items start with @samp{1.} or @samp{1)}. Items +is supported, it may be better to not use it for plain list items.} as +bullets. Ordered list items start with a numeral followed by either a +period or a right parenthesis, such as @samp{1.} or @samp{1)}. Items belonging to the same list must have the same indentation on the first line. In particular, if an ordered list reaches number @samp{10.}, then the 2--digit numbers must be written left-aligned with the other numbers @@ -1181,9 +1183,9 @@ the command chain with a cursor motion or so. @kindex C-c C-c @item C-c C-c If there is a checkbox (@pxref{Checkboxes}) in the item line, toggle the -state of the checkbox. If not, make this command makes sure that all -the items on this list level use the same bullet. Furthermore, if this -is an ordered list, make sure the numbering is ok. +state of the checkbox. If not, this command makes sure that all the +items on this list level use the same bullet. Furthermore, if this is +an ordered list, make sure the numbering is ok. @kindex C-c - @item C-c - Cycle the entire list level through the different itemize/enumerate @@ -1200,7 +1202,7 @@ Sometimes you want to keep information associated with an entry, but you normally don't want to see it. For this, Org-mode has @emph{drawers}. Drawers need to be configured with the variable @code{org-drawers}@footnote{You can define drawers on a per-file basis -with a line like @code{#+DRAWERS: HIDDEN PROPPERTIES STATE}}, and +with a line like @code{#+DRAWERS: HIDDEN PROPERTIES STATE}}. Drawers look like this: @example @@ -1246,9 +1248,16 @@ silently in the shadow. @cindex tables @cindex editing tables -Org-mode has a very fast and intuitive table editor built-in. -Spreadsheet-like calculations are supported in connection with the -Emacs @file{calc} package. +Org-mode comes with a fast and intuitive table editor. Spreadsheet-like +calculations are supported in connection with the Emacs @file{calc} +package +@ifinfo +(@pxref{Calc,,,calc,Gnu Emacs Calculator Manual}). +@end ifinfo +@ifnotinfo +(see the Emacs Calculator manual for more information about the Emacs +calculator). +@end ifnotinfo @menu * Built-in table editor:: Simple tables @@ -2145,8 +2154,8 @@ series of degree @code{n} at location @code{x} for a couple of functions @chapter Hyperlinks @cindex hyperlinks -Just like HTML, Org-mode provides links inside a file, and external -links to other files, Usenet articles, emails, and much more. +Like HTML, Org-mode provides links inside a file, external links to +other files, Usenet articles, emails, and much more. @menu * Link format:: How links in Org-mode are formatted @@ -2600,16 +2609,16 @@ file. @chapter TODO items @cindex TODO items -Org-mode does not maintain TODO lists as a separate document. TODO -items are an integral part of the notes file, because TODO items -usually come up while taking notes! With Org-mode, you simply mark -any entry in a tree as being a TODO item. In this way, the -information is not duplicated, and the entire context from which the -item emerged is always present when you check. +Org-mode does not maintain TODO lists as separate documents. Instead, +TODO items are an integral part of the notes file, because TODO items +usually come up while taking notes! With Org-mode, simply mark any +entry in a tree as being a TODO item. In this way, information is not +duplicated, and the entire context from which the TODO item emerged is +always present. -Of course, this technique causes TODO items to be scattered throughout -your file. Org-mode provides methods to give you an overview over all -things you have to do. +Of course, this technique for managing TODO items scatters them +throughout your notes file. Org-mode compensates for this by providing +methods to give you an overview of all the things that you have to do. @menu * TODO basics:: Marking and displaying TODO entries @@ -2623,8 +2632,8 @@ things you have to do. @node TODO basics, TODO extensions, TODO items, TODO items @section Basic TODO functionality -Any headline can become a TODO item by starting it with the word TODO, -for example: +Any headline becomes a TODO item when it starts with the word +@samp{TODO}, for example: @example *** TODO Write letter to Sam Fortune @@ -2649,24 +2658,24 @@ agenda buffers with the @kbd{t} command key (@pxref{Agenda commands}). @kindex C-u C-c C-t @item C-u C-c C-t -Select a specific keyword using completion of (if it has been set up) +Select a specific keyword using completion or (if it has been set up) the fast selection interface. @kindex S-@key{right} @kindex S-@key{left} @item S-@key{right} @itemx S-@key{left} -Select the following/preceding TODO state, similar to cycling. Mostly -useful if more than two TODO states are possible (@pxref{TODO +Select the following/preceding TODO state, similar to cycling. Useful +mostly if more than two TODO states are possible (@pxref{TODO extensions}). @kindex C-c C-c @item C-c C-c -Use the fast tag interface to quickly and directly select a specific -TODO state. For this you need to assign keys to TODO state, like this: +Use the fast tag interface to directly select a specific TODO state. +For this you need to assign keys to TODO states, like this: @example #+SEQ_TODO: TODO(t) STARTED(s) WAITING(w) | DONE(d) @end example -@noindent See @ref{Per file keywords} and @ref{Setting tags} for more +@noindent See @ref{Per-file keywords} and @ref{Setting tags} for more information. @kindex C-c C-v @kindex C-c / t @@ -2682,11 +2691,11 @@ 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 -agenda files (@pxref{Agenda views}) into a single buffer. The buffer is in -@code{agenda-mode}, so there are commands to examine and manipulate -the TODO entries directly from that buffer (@pxref{Agenda commands}). -@xref{Global TODO list}, for more information. +Show the global TODO list. Collects the TODO items from all agenda +files (@pxref{Agenda views}) into a single buffer. The new buffer will +be in @code{agenda-mode}, which provides commands to examine and +manipulate the TODO entries from the new buffer (@pxref{Agenda +commands}). @xref{Global TODO list}, for more information. @kindex S-M-@key{RET} @item S-M-@key{RET} Insert a new TODO entry below the current one. @@ -2696,20 +2705,21 @@ Insert a new TODO entry below the current one. @section Extended use of TODO keywords @cindex extended TODO keywords -The default implementation of TODO entries is just two states: TODO and -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. +By default, marked TODO entries have one of only two states: TODO and +DONE. Org-mode allows you to classify TODO items in more complex ways +with @emph{TODO keywords} (stored in @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}). @menu * Workflow states:: From TODO to DONE in steps -* TODO types:: I do this, Fred the rest +* TODO types:: I do this, Fred does the rest * Multiple sets in one file:: Mixing it all, and still finding your way * Fast access to TODO states:: Single letter selection of a state -* Per file keywords:: Different files, different requirements +* Per-file keywords:: Different files, different requirements * Faces for TODO keywords:: Highlighting states @end menu @@ -2818,7 +2828,7 @@ These keys jump from one TODO subset to the next. In the above example, would switch from @code{DONE} to @code{REPORT} in the example above. @end table -@node Fast access to TODO states, Per file keywords, Multiple sets in one file, TODO extensions +@node Fast access to TODO states, Per-file keywords, Multiple sets in one file, TODO extensions @subsection Fast access to TODO states If you would like to quickly change an entry to an arbitrary TODO state @@ -2842,10 +2852,10 @@ the default. Check also the variable @code{org-fast-tag-selection-include-todo}, it allows to change the TODO state through the tags interface (@pxref{Setting tags}). -@node Per file keywords, Faces for TODO keywords, Fast access to TODO states, TODO extensions +@node Per-file keywords, Faces for TODO keywords, Fast access to TODO states, TODO extensions @subsection Setting up keywords for individual files @cindex keyword options -@cindex per file keywords +@cindex per-file keywords 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 @@ -2885,7 +2895,7 @@ 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 Faces for TODO keywords, , Per file keywords, TODO extensions +@node Faces for TODO keywords, , Per-file keywords, TODO extensions @subsection Faces for TODO keywords @cindex faces, for TODO keywords @@ -2985,20 +2995,24 @@ states with an additional @samp{@@}, like this: @section Priorities @cindex priorities -If you use Org-mode extensively to organize your work, you may end up -with a number of TODO entries so large that you'd like to prioritize -them. This can be done by placing a @emph{priority cookie} into the -headline, like this +If you use Org-mode extensively, you may end up enough TODO items that +it starts to make sense to prioritize them. Prioritizing can be done by +placing a @emph{priority cookie} into the headline of a TODO item, like +this @example *** TODO [#A] Write letter to Sam Fortune @end example @noindent -With its standard setup, Org-mode supports priorities @samp{A}, -@samp{B}, and @samp{C}. @samp{A} is the highest priority. An entry -without a cookie is treated as priority @samp{B}. Priorities make a -difference only in the agenda (@pxref{Weekly/Daily agenda}). +By default, Org-mode supports three priorities: @samp{A}, @samp{B}, and +@samp{C}. @samp{A} is the highest priority. An entry without a cookie +is treated as priority @samp{B}. Priorities make a difference only in +the agenda (@pxref{Weekly/Daily agenda}); outside the agenda, they have +no inherent meaning to Org-mode. + +Priorities can be attached to any outline tree entries; they do not need +to be TODO items. @table @kbd @kindex @kbd{C-c ,} @@ -3047,13 +3061,15 @@ of checkboxes to identify (a hierarchy of) a large number of subtasks @section Checkboxes @cindex checkboxes -Every item in a plain list (@pxref{Plain lists}) can be made a checkbox -by starting it with the string @samp{[ ]}. This feature is similar to -TODO items (@pxref{TODO items}), but more lightweight. Checkboxes are -not included into the global TODO list, so they are often great to split -a task into a number of simple steps. Or you can use them in a shopping -list. To toggle a checkbox, use @kbd{C-c C-c}, or try Piotr Zielinski's -@file{org-mouse.el}. Here is an example of a checkbox list. +Every item in a plain list (@pxref{Plain lists}) can be made into a +checkbox by starting it with the string @samp{[ ]}. This feature is +similar to TODO items (@pxref{TODO items}), but is more lightweight. +Checkboxes are not included into the global TODO list, so they are often +great to split a task into a number of simple steps. Or you can use +them in a shopping list. To toggle a checkbox, use @kbd{C-c C-c}, or +use the mouse (thanks to Piotr Zielinski's @file{org-mouse.el}). + +Here is an example of a checkbox list. @example * TODO Organize party [3/6] @@ -3069,16 +3085,17 @@ list. To toggle a checkbox, use @kbd{C-c C-c}, or try Piotr Zielinski's @cindex statistics, for checkboxes @cindex checkbox statistics The @samp{[3/6]} and @samp{[1/3]} in the first and second line are -cookies indicating how many checkboxes are present in this entry, and -how many of them have been checked off. This can give you an idea on -how many checkboxes remain, even without opening a folded entry. The -cookies can be placed into a headline or into (the first line of) a -plain list item. Each cookie covers all checkboxes structurally below -that headline/item. You have to insert the cookie yourself by typing -either @samp{[/]} or @samp{[%]}. In the first case you get an @samp{n -out of m} result, in the second case you get information about the +cookies indicating how many checkboxes present in this entry have been +checked off, and the total number of checkboxes are present. This can +give you an idea on how many checkboxes remain, even without opening a +folded entry. The cookies can be placed into a headline or into (the +first line of) a plain list item. Each cookie covers all checkboxes +structurally below the headline/item on which the cookie appear. You +have to insert the cookie yourself by typing either @samp{[/]} or +@samp{[%]}. With @samp{[/]} you get an @samp{n out of m} result, as in +the examples above. With @samp{[%]} you get information about the percentage of checkboxes checked (in the above example, this would be -@samp{[50%]} and @samp{[33%], respectively}). +@samp{[50%]} and @samp{[33%]}, respectively). @noindent The following commands work with checkboxes: @@ -3117,7 +3134,6 @@ delete boxes or add/change them by hand, use this command to get things back into synch. Or simply toggle any checkbox twice with @kbd{C-c C-c}. @end table - @node Tags, Properties and columns, TODO items, Top @chapter Tags @cindex tags @@ -3125,14 +3141,15 @@ back into synch. Or simply toggle any checkbox twice with @kbd{C-c C-c}. @cindex matching, tags @cindex sparse tree, tag based -If you wish to implement a system of labels and contexts for -cross-correlating information, an excellent way is to assign @i{tags} to -headlines. Org-mode has extensive support for using tags. +An excellent way to implement labels and contexts for cross-correlating +information is to assign @i{tags} to headlines. Org-mode has extensive +support for tags. -Every headline can contain a list of tags, at the end of the headline. -Tags are normal words containing letters, numbers, @samp{_}, and -@samp{@@}. Tags must be preceded and followed by a single colon; like -@samp{:WORK:}. Several tags can be specified like @samp{:work:URGENT:}. +Every headline can contain a list of tags; they occur at the end of the +headline. Tags are normal words containing letters, numbers, @samp{_}, +and @samp{@@}. Tags must be preceded and followed by a single colon, +e.g., @samp{:WORK:}. Several tags can be specified, as in +@samp{:work:URGENT:}. @menu * Tag inheritance:: Tags use the tree structure of the outline @@ -3158,13 +3175,14 @@ well. For example, in the list @noindent the final heading will have the tags @samp{:work:}, @samp{:boss:}, -@samp{:notes:}, and @samp{:action:}. When executing tag searches and +@samp{:notes:}, and @samp{:action:} even though the final heading is not +explicitly marked with those tags. When executing tag searches and Org-mode finds that a certain headline matches the search criterion, it -will not check any sublevel headline, assuming that these likely also -match, and that the list of matches can become very long. This may -not be what you want, however, and you can influence inheritance and -searching using the variables @code{org-use-tag-inheritance} and -@code{org-tags-match-list-sublevels}. +will not check any sublevel headline, assuming that these also match and +that the list of matches could become very long because of that. If you +do want the subevels be tested and listed as well, you may set the +variable @code{org-tags-match-list-sublevels}. To turn off tag +inheritance entirely, use the variable @code{org-use-tag-inheritance}. @node Setting tags, Tag searches, Tag inheritance, Tags @section Setting tags @@ -3202,7 +3220,7 @@ the default tags for a given file with lines like If you have globally defined your preferred set of tags using the variable @code{org-tag-alist}, but would like to use a dynamic tag list -in a specific file: Just add an empty TAGS option line to that file: +in a specific file, add an empty TAGS option line to that file: @example #+TAGS: @@ -3301,7 +3319,7 @@ when you press an extra @kbd{C-c}. @cindex tag searches @cindex searching for tags -Once a tags system has been set up, it can be used to collect related +Once a system of tags has been set up, it can be used to collect related information into special lists. @table @kbd @@ -3385,6 +3403,25 @@ tag @samp{boss} and are @emph{not} marked with the todo keyword DONE. Properties are a set of key-value pairs associated with an entry. There are two main applications for properties in Org-mode. First, properties +are like tags, but with a value. Second, you can use properties to +implement (very basic) database capabilities in an Org-mode buffer. For +an example of the first application, imagine maintaining a file where +you document bugs and plan releases of a piece of software. Instead of +using tags like @code{:release_1:}, @code{:release_2:}, one can use a +property, say @code{Release}, that in different subtrees has different +values, such as @code{1.0} or @code{2.0}. For an example of the second +application of properties, imagine keeping track of one's music CD's, +where properties could be things such as the album artist, date of +release, number of tracks, and so on. + +Properties can be conveiently edited and viewed in column view +(@pxref{Column view}). + + + + + + are like tags, but with a value. For example, in a file where you document bugs and plan releases of a piece of software, instead of using tags like @code{:release_1:}, @code{:release_2:}, it can be more @@ -3826,10 +3863,10 @@ property API}. @cindex time stamps @cindex date stamps -Items can be labeled with a date and/or a time to make them useful for -project planning. The specially formatted string carrying the date and -time information is called a @emph{timestamp} in Org-mode. This may be -a little confusing because timestamp is often used as indicating when +To assist project planning, TODO items can be labeled with a date and/or +a time. The specially formatted string carrying the date and time +information is called a @emph{timestamp} in Org-mode. This may be a +little confusing because timestamp is often used as indicating when something was created or last changed. However, in Org-mode this term is used in a much wider sense. @@ -3852,10 +3889,10 @@ is used in a much wider sense. A time stamp is a specification of a date (possibly with time or a range of times) in a special format, either @samp{<2003-09-16 Tue>} or @samp{<2003-09-16 Tue 09:39>} or @samp{<2003-09-16 Tue -12:00-12:30>}@footnote{This is the standard ISO date/time format. If -you cannot get used to these, see @ref{Custom time format}}. A time -stamp can appear anywhere in the headline or body of an org-tree entry. -Its presence causes entries to be shown on specific dates in the agenda +12:00-12:30>}@footnote{This is the standard ISO date/time format. To +use an alternative format, see @ref{Custom time format}.}. A time stamp +can appear anywhere in the headline or body of an org-tree entry. Its +presence causes entries to be shown on specific dates in the agenda (@pxref{Weekly/Daily agenda}). We distinguish: @table @var @@ -4131,17 +4168,20 @@ format is shorter, things do work as expected. @node Deadlines and scheduling, Clocking work time, Creating timestamps, Dates and times @section Deadlines and Scheduling -A time stamp may be preceded by special keywords to facilitate planning -of work: +A time stamp may be preceded by special keywords to facilitate planning: @table @var @item DEADLINE @cindex DEADLINE keyword -The task (most likely a TODO item) is supposed to be finished on that -date, and it will be listed then. In addition, the compilation for -@emph{today} will carry a warning about the approaching or missed -deadline, starting @code{org-deadline-warning-days} before the due date, -and continuing until the entry is marked DONE. An example: + +Meaning: the task (most likely a TODO item, though not necessarily) is supposed +to be finished on that date. + +On the deadline date, the task will be listed in the agenda. In +addition, the agenda for @emph{today} will carry a warning about the +approaching or missed deadline, starting +@code{org-deadline-warning-days} before the due date, and continuing +until the entry is marked DONE. An example: @example *** TODO write article about the Earth for the Guide @@ -4155,9 +4195,12 @@ period of 5 days @code{DEADLINE: <2004-02-29 Sun -5d>}. @item SCHEDULED @cindex SCHEDULED keyword -You are planning to start working on that task on the given date. The -headline will be listed under the given date@footnote{It will still be -listed on that date after it has been marked DONE. If you don't like + +Meaning: you are planning to start working on that task on the given +date. + +The headline will be listed under the given date@footnote{It will still +be listed on that date after it has been marked DONE. If you don't like this, set the variable @code{org-agenda-skip-scheduled-if-done}.}. In addition, a reminder that the scheduled date has passed will be present in the compilation for @emph{today}, until the entry is marked DONE. @@ -4170,12 +4213,12 @@ I.e., the task will automatically be forwarded until completed. @noindent @b{Important:} Scheduling an item in Org-mode should @i{not} be -understood like @i{Scheduling a meeting}. Setting a date for a meeting -is just a simple appointment, you should mark this entry with a simple -plain time stamp, to get this item shown on the date where it applies. -This is a frequent mis-understanding from Org-users. In Org-mode, -@i{Scheduling} means setting a date when you want to start working on an -action item. +understood in the same way that we understand @i{scheduling a meeting}. +Setting a date for a meeting is just a simple appointment, you should +mark this entry with a simple plain time stamp, to get this item shown +on the date where it applies. This is a frequent mis-understanding from +Org-users. In Org-mode, @i{scheduling} means setting a date when you +want to start working on an action item. @end table @menu @@ -4218,13 +4261,16 @@ the scheduling date from the entry. @node Repeated tasks, , Inserting deadline/schedule, Deadlines and scheduling @subsection Repeated Tasks -Some tasks need to be repeated again and again, and Org-mode therefore -allows to use a repeater in a DEADLINE or SCHEDULED time stamp, for -example: +Some tasks need to be repeated again and again. Org-mode helps to +organize such tasks using a so-called repeater in a DEADLINE or +SCHEDULED time stamp. In the following example @example ** TODO Pay the rent DEADLINE: <2005-10-01 Sat +1m> @end example +the @code{+1m} is a repeater; the intended interpretation is that the +task has a deadline on <2005-10-01> and repeats itself every (one) month +starting from that time. Deadlines and scheduled items produce entries in the agenda when they are over-due, so it is important to be able to mark such an entry as @@ -4453,6 +4499,9 @@ During expansion of the template, special @kbd{%}-escapes allow dynamic insertion of content: @example %^@{prompt@} @r{prompt the user for a string and replace this sequence with it.} + @r{You may specify a default value and a completion table with} + @r{%^@{prompt|default|completion2|completion3...@}} + @r{The arrow keys access a prompt-specific history.} %t @r{time stamp, date only} %T @r{time stamp with date and time} %u, %U @r{like the above, but inactive time stamps} @@ -4469,6 +4518,8 @@ insertion of content: %:keyword @r{specific information for certain link types, see below} %[pathname] @r{insert the contents of the file given by @code{pathname}} %(sexp) @r{evaluate elisp @code{(sexp)} and replace with the result} +%! @r{immediately store note after completing the template} + @r{(skipping the @kbd{C-c C-c} that normally triggers storing)} @end example @noindent @@ -4507,11 +4558,11 @@ template that will be filled with the previous context information. @node Storing notes, Refiling notes, Remember templates, Remember @section Storing notes -When you are finished preparing a note with @i{remember}, you have to press -@kbd{C-c C-c} to file the note away. The handler will store the note in -the file and under the headline specified in the template, or it will -use the default file and headlines. The window configuration will be -restored, and you are back in the working context before the call to +When you are finished preparing a note with @i{remember}, you have to +press @kbd{C-c C-c} to file the note away. The handler will store the +note in the file and under the headline specified in the template, or it +will use the default file and headlines. The window configuration will +be restored, sending you back to the working context before the call to @code{remember}. To re-use the location found during the last call to @code{remember}, exit the remember buffer with @kbd{C-u C-u C-c C-c}, i.e. specify a double prefix argument to @kbd{C-c C-c}. @@ -4589,8 +4640,8 @@ argument (@kbd{C-u C-u}) to this command. Due to the way Org-mode works, TODO items, time-stamped items, and tagged headlines can be scattered throughout a file or even a number of -files. To get an overview over open action items, or over events that -are important for a particular date, this information must be collected, +files. To get an overview of open action items, or of events that are +important for a particular date, this information must be collected, sorted and displayed in an organized way. Org-mode can select items based on various criteria, and display them @@ -7475,18 +7526,17 @@ org-convert-to-oddeven-levels}. @section Using org-mode on a tty @cindex tty keybindings -Org-mode uses a number of keys that are not accessible on a tty. This -applies to most special keys like cursor keys, @key{TAB} and -@key{RET}, when these are combined with modifier keys like @key{Meta} -and/or @key{Shift}. Org-mode uses these bindings because it needs to -provide keys for a large number of commands, and because these keys -appeared particularly easy to remember. In order to still be able to -access the core functionality of Org-mode on a tty, alternative -bindings are provided. Here is a complete list of these bindings, -which are obviously more cumbersome to use. Note that sometimes a -work-around can be better. For example changing a time stamp is -really only fun with @kbd{S-@key{cursor}} keys. On a tty you would -rather use @kbd{C-c .} to re-insert the timestamp. +Because Org-mode contains a large number of commands, by default much of +Org-mode's core commands are bound to keys that are generally not +accessible on a tty, such as the cursor keys (@key{left}, @key{right}, +@key{up}, @key{down}), @key{TAB} and @key{RET}, in particular when used +together with modifiers like @key{Meta} and/or @key{Shift}. To access +these commands on a tty when special keys are unavailable, the following +alternative bindings can be used. The tty bindings below will likely be +more cumbersome; you may find for some of the bindings below that a +customized work-around suits you better. For example, changing a time +stamp is really only fun with @kbd{S-@key{cursor}} keys, whereas on a +tty you would rather use @kbd{C-c .} to re-insert the timestamp. @multitable @columnfractions 0.15 0.2 0.2 @item @b{Default} @tab @b{Alternative 1} @tab @b{Alternative 2} @@ -7753,7 +7803,7 @@ Translates Org-mode files into something readable by Remind. @url{http://www.cognition.ens.fr/~guerry/u/org2rem.el}. @item @file{org-toc.el} by Bastien Guerry Produces a simple table of contents of an Org-mode file, for easy -navigation. @url{http://www.cognition.ens.fr/~guerry/u/org2rem.el}. +navigation. @url{http://www.cognition.ens.fr/~guerry/u/org-registry.el}. @item @file{org-registry.el} by Bastien Guerry Find which Org-file link to a certain document. @url{http://www.cognition.ens.fr/~guerry/u/org2rem.el}. @@ -8357,7 +8407,7 @@ Get all property keys in the current buffer. Insert a property drawer at point. @end defun -@node History and Acknowledgments, Main Index, Extensions and Hacking, Top +@node History and Acknowledgments, Index, Extensions and Hacking, Top @appendix History and Acknowledgments @cindex acknowledgments @cindex history @@ -8532,12 +8582,12 @@ and contributed various ideas and code snippets. @end itemize -@node Main Index, Key Index, History and Acknowledgments, Top -@unnumbered Main Index +@node Index, Key Index, History and Acknowledgments, Top +@unnumbered The Main Index @printindex cp -@node Key Index, , Main Index, Top +@node Key Index, , Index, Top @unnumbered Key Index @printindex ky diff --git a/orgcard.pdf b/orgcard.pdf index 70c61d480..bd6f1e467 100644 Binary files a/orgcard.pdf and b/orgcard.pdf differ diff --git a/orgcard.tex b/orgcard.tex index 9de74edf4..9179fdfb8 100644 --- a/orgcard.tex +++ b/orgcard.tex @@ -1,5 +1,5 @@ % Reference Card for Org Mode -\def\orgversionnumber{5.16a} +\def\orgversionnumber{5.17} \def\versionyear{2007} % latest update \def\year{2007} % latest copyright year