diff --git a/org b/org index 07c3ad692..7e9fa791b 100644 --- a/org +++ b/org @@ -5,7 +5,7 @@ START-INFO-DIR-ENTRY * Org Mode: (org). outline-based notes management and organizer END-INFO-DIR-ENTRY - This manual is for Org-mode (version 4.50). + This manual is for Org-mode (version 4.51). Copyright (C) 2004, 2005, 2006 Free Software Foundation @@ -27,7 +27,7 @@ File: org, Node: Top, Next: Introduction, Prev: (dir), Up: (dir) Org Mode Manual *************** -This manual is for Org-mode (version 4.50). +This manual is for Org-mode (version 4.51). Copyright (C) 2004, 2005, 2006 Free Software Foundation @@ -111,6 +111,7 @@ Hyperlinks * Internal links:: Links to other places in the current file * External links:: URL-like links to the world * Handling links:: Creating, inserting and following +* Link abbreviations:: Shortcuts for writing complex links * Search options:: Linking to a specific location * Custom searches:: When the default search is not enough * Remember:: Org-trees store quick notes @@ -140,6 +141,10 @@ Timestamps * Creating timestamps:: Commands which insert timestamps * Progress logging:: Documenting when what work was done. +Creating timestamps + +* The date/time prompt:: + Progress Logging * Closing items:: When was this entry marked DONE? @@ -1445,6 +1450,7 @@ links to other files, Usenet articles, emails, and much more. * Internal links:: Links to other places in the current file * External links:: URL-like links to the world * Handling links:: Creating, inserting and following +* Link abbreviations:: Shortcuts for writing complex links * Search options:: Linking to a specific location * Custom searches:: When the default search is not enough * Remember:: Org-trees store quick notes @@ -1553,9 +1559,11 @@ File: org, Node: CamelCase links, Prev: Radio targets, Up: Internal links Org-mode also supports CamelCase words as links. This feature is not turned on by default because of the inconsistencies this system suffers -from. To activate CamelCase words as links, you need to customize the -option `org-activate-links'. A CamelCase word then leads to a text -search such that `CamelCaseLink' is equivalent to `[[camel case link]]'. +from. It is also possible that this feature will disappear entirely in +a future version of Org-mode. To activate CamelCase words as links, you +need to customize the option `org-activate-links'. A CamelCase word +then leads to a text search such that `CamelCaseLink' is equivalent to +`[[camel case link]]'.  File: org, Node: External links, Next: Handling links, Prev: Internal links, Up: Hyperlinks @@ -1601,7 +1609,7 @@ them as links. If spaces must be part of the link (for example in end of the link, enclose them in angular brackets.  -File: org, Node: Handling links, Next: Search options, Prev: External links, Up: Hyperlinks +File: org, Node: Handling links, Next: Link abbreviations, Prev: External links, Up: Hyperlinks 4.4 Handling links ================== @@ -1678,7 +1686,8 @@ insert it into an org-mode file, and to follow the link. Under Emacs 22, also `mouse-1' will follow a link. `mouse-3' - Like `mouse-2', but force file links to be opened with Emacs. + Like `mouse-2', but force file links to be opened with Emacs, and + internal links to be displayed in another window(2). `C-c %' Push the current position onto the mark ring, to be able to return @@ -1697,10 +1706,53 @@ the list of stored links. To keep it in the list later use, use a triple `C-u' prefix to `C-c C-l', or configure the option `org-keep-stored-link-after-insertion'. - -File: org, Node: Search options, Next: Custom searches, Prev: Handling links, Up: Hyperlinks + (2) See the variable `org-display-internal-link-with-indirect-buffer' -4.5 Search options in file links + +File: org, Node: Link abbreviations, Next: Search options, Prev: Handling links, Up: Hyperlinks + +4.5 Link abbreviatons +===================== + +Long URLs can be cumbersome to type, and often many similar links are +needed in a document. For this you can use link abbreviations. An +abbreviated link looks like this + + [[linkword::tag][description]] + +where the tag is optional. Such abbreviations are resolved according to +the information in the variable `org-link-abbrev-alist' that relates +the linkwords to replacement text. Here is an example: + + (setq org-link-abbrev-alist + '(("bugzilla" . "http://10.1.2.9/bugzilla/show_bug.cgi?id=") + ("google" . "http://www.google.com/search?q=") + ("ads" . "http://adsabs.harvard.edu/cgi-bin/ + nph-abs_connect?author=%s&db_key=AST"))) + + If the replacement text contains the string `%s', it will be +replaced with the tag. Otherwise the tag will be appended to the string +in order to create the link. You may also specify a function that will +be called with the tag as the only argument to create the link. + + With the above setting, you could link to a specific bug with +`[[bugzilla::129]]', search the web for OrgMode with +`[[google::OrgMode]]' and find out what the Org-mode author is doing +besides Emacs hacking with `[[ads::Dominik,C]]'. + + If you need special abbreviations just for a single Org-mode buffer, +you can define them in the file with + + #+LINK: bugzilla http://10.1.2.9/bugzilla/show_bug.cgi?id= + #+LINK: google http://www.google.com/search?q=%s + +In-buffer completion *note Completion:: can be used after `[' to +complete link abbreviations. + + +File: org, Node: Search options, Next: Custom searches, Prev: Link abbreviations, Up: Hyperlinks + +4.6 Search options in file links ================================ File links can contain additional information to make Emacs jump to a @@ -1750,7 +1802,7 @@ single colon.  File: org, Node: Custom searches, Next: Remember, Prev: Search options, Up: Hyperlinks -4.6 Custom Searches +4.7 Custom Searches =================== The default mechanism for creating search strings and for doing the @@ -1772,7 +1824,7 @@ implementation example. Search for `BibTeX links' in the source file.  File: org, Node: Remember, Prev: Custom searches, Up: Hyperlinks -4.7 Remember +4.8 Remember ============ Another way to create org entries with links to other files is through @@ -2303,12 +2355,37 @@ format. end. With prefix arg, insert result after the time range (in a table: into the following column). - When Org-mode prompts for a date/time, the function reading your -input will replace anything you choose not to specify with the current -date and time. For details, see the documentation string of -`org-read-date'. Also, a calender will pop up to allow selecting a -date. The calendar can be fully controlled from the minibuffer, and a -date can be selected with the following commands: +* Menu: + +* The date/time prompt:: + + +File: org, Node: The date/time prompt, Prev: Creating timestamps, Up: Creating timestamps + +6.2.1 The date/time prompt +-------------------------- + +When Org-mode prompts for a date/time, the prompt suggests to enter an +ISO date. But it will in fact accept any string containing some date +and/or time information. You can, for example, use `C-y' to paste a +(possibly multi-line) string copied from an email message. Org-mode +will find whatever information is in there and will replace anything not +specified with the current date and time. For example: + + 3-2-5 --> 2003-02-05 + feb 15 --> currentyear-02-15 + sep 12 9 --> 2009-09-12 + 12:45 --> today 12:45 + 22 sept 0:34 --> currentyear-09-22 0:34 + 12 --> currentyear-currentmonth-12 + Fri --> nearest Friday (today or later) + + The function understands English month and weekday abbreviations. If +you want to use unabbreviated names and/or other languages, configure +the variables `parse-time-months' and `parse-time-weekdays'. + + Parallel to the minibuffer prompt, a calendar is popped up(1). You +can control the calendar fully from the minibuffer: `<' Scroll calendar backwards by one month. @@ -2340,6 +2417,11 @@ date can be selected with the following commands: `' Choose date in calendar (only if nothing typed into minibuffer). + ---------- Footnotes ---------- + + (1) If you don't need/want the calendar, configure the variable +`org-popup-calendar-for-date-prompt'. +  File: org, Node: Progress logging, Prev: Creating timestamps, Up: Timestamps @@ -2649,6 +2731,10 @@ This buffer is read-only, but provides commands to visit the corresponding locations in the original Org-mode files, and even to edit these files remotely. + Two variables control how the agenda buffer is displayed and whether +the window configuration is restored when the agenda exits: +`org-agenda-window-setup' and `org-agenda-restore-windows-after-quit'. + * Menu: * Agenda files:: Files being searched for agenda information @@ -4280,6 +4366,9 @@ buffer and use the key to complete text right there. in-buffer option, *note Setting tags::), or it is created dynamically from all tags used in the current buffer. + * After `[', complete link abbreviations (*note Link + abbreviations::). + * After `#+', complete the special keywords like `TYP_TODO' or `OPTIONS' which set file-specific options for Org-mode. When the option keyword is already complete, pressing `M-' @@ -4359,6 +4448,11 @@ file is visited again in a new Emacs session. tags in this file, and (potentially) the corresponding _fast tag selection_ keys. The corresponding variable is `org-tag-alist'. +`#+LINK: linkword replace' + These lines (several are allowed) specify link abbreviations. + *Note Link abbreviations::. The corresponding variable is + `org-link-abbrev-alist'. + `#+CATEGORY:' This line sets the category for the agenda file. The category applies for all subsequent lines until the next `#+CATEGORY' line, @@ -4873,6 +4967,8 @@ if I have forgotten someone, please accept my apologies and let me know. * Daniel Sinder came up with the idea of internal archiving by locking subtrees. + * Dale Smith proposed link abbreviations. + * David O'Toole wrote `org-publish.el' and drafted the manual chapter about publishing. @@ -4910,6 +5006,7 @@ Index [index] * Menu: +* abbreviation, links: Link abbreviations. (line 6) * acknowledgments: History and Acknowledgments. (line 6) * action, for publishing: Publishing action. (line 6) @@ -4925,6 +5022,7 @@ Index * agenda files, removing buffers: Agenda commands. (line 211) * agenda views: Agenda views. (line 6) * agenda views, custom: Custom agenda views. (line 6) +* agenda, batch production: Batch processing. (line 6) * agenda, with block views: Block agenda. (line 6) * allout.el: Conflicts. (line 6) * angular brackets, around links: External links. (line 38) @@ -4939,6 +5037,8 @@ Index * bold text: Enhancing text. (line 15) * bug reports: Feedback. (line 6) * bugs: Bugs. (line 6) +* C-c C-c, overview: The very busy C-c C-c key. + (line 6) * calc package: Table calculations. (line 6) * calc.el: Cooperation. (line 6) * calculations, in tables <1>: Table calculations. (line 6) @@ -4947,11 +5047,13 @@ Index * calendar commands, from agenda: Agenda commands. (line 172) * calendar integration: Calendar/Diary integration. (line 6) -* calendar, for selecting date: Creating timestamps. (line 71) +* calendar, for selecting date: The date/time prompt. + (line 25) * CamelCase link completion: Completion. (line 6) * CamelCase links: Internal links. (line 6) * CamelCase links, completion of: CamelCase links. (line 6) * category: Categories. (line 6) +* CDLaTeX: CDLaTeX mode. (line 6) * cdlatex.el: Cooperation. (line 29) * checkbox statistics: Checkboxes. (line 23) * checkboxes: Checkboxes. (line 6) @@ -4988,8 +5090,10 @@ Index * cycling, of TODO states: TODO basics. (line 13) * cycling, visibility: Visibility cycling. (line 6) * daily agenda: Weekly/Daily agenda. (line 6) -* date stamps: Time stamps. (line 6) -* date, reading in minibuffer: Creating timestamps. (line 71) +* date stamps <1>: Time stamps. (line 6) +* date stamps: Timestamps. (line 6) +* date, reading in minibuffer: The date/time prompt. + (line 6) * DEADLINE keyword: Time stamps. (line 43) * deadlines: Time stamps. (line 6) * demotion, of subtrees: Structure editing. (line 6) @@ -5021,6 +5125,7 @@ Index * file links: External links. (line 6) * file links, searching: Search options. (line 6) * file name completion: Handling links. (line 43) +* files for agenda: Agenda files. (line 6) * files, adding to agenda list: Agenda files. (line 12) * files, selecting for publishing: Selecting files. (line 6) * fixed width: Enhancing text. (line 25) @@ -5072,29 +5177,36 @@ Index * jumping, to headlines: Motion. (line 6) * keybindings, global: Activation. (line 6) * keyword options: Per file keywords. (line 6) -* LaTeX fragments: Export options. (line 25) +* LaTeX fragments <1>: Export options. (line 25) +* LaTeX fragments: LaTeX fragments. (line 6) * LaTeX fragments, export: Enhancing text. (line 18) +* LaTeX fragments, preview: Processing LaTeX fragments. + (line 6) * LaTeX interpretation: Embedded LaTeX. (line 6) * linebreak preservation: Export options. (line 25) * linebreak, forced: Enhancing text. (line 32) +* link abbreviations: Link abbreviations. (line 6) * link completion: Handling links. (line 27) * link format: Link format. (line 6) * links, external: External links. (line 6) +* links, handling: Handling links. (line 6) * links, in HTML export: HTML export. (line 35) * links, internal: Internal links. (line 6) * links, publishing: Publishing links. (line 6) -* links, returning to: Handling links. (line 84) +* links, radio targets: Radio targets. (line 6) +* links, returning to: Handling links. (line 85) * Lisp forms, as table formulas: Lisp formulas. (line 6) * lists, hand-formatted: Enhancing text. (line 11) * lists, ordered: Plain lists. (line 6) * lists, plain: Plain lists. (line 6) * logging, of progress: Progress logging. (line 6) * maintainer: Feedback. (line 6) -* mark ring: Handling links. (line 80) +* mark ring: Handling links. (line 81) * marking characters, tables: Advanced features. (line 34) * matching, of tags: Matching headline tags. (line 6) * matching, tags: Tags. (line 6) +* math symbols: Math symbols. (line 6) * MH-E links: External links. (line 6) * minor mode for tables: orgtbl-mode. (line 6) * mode, for calc: Formula syntax. (line 34) @@ -5140,6 +5252,7 @@ Index * promotion, of subtrees: Structure editing. (line 6) * publishing: Publishing. (line 6) * quoted HTML tags: Export options. (line 25) +* radio targets: Radio targets. (line 6) * ranges, time: Time stamps. (line 6) * recomputing table fields: Column formulas. (line 27) * region, active <1>: HTML export. (line 10) @@ -5155,6 +5268,8 @@ Index * SCHEDULED keyword: Time stamps. (line 30) * scheduling: Time stamps. (line 6) * search option in file links: Search options. (line 6) +* search strings, custom: Custom searches. (line 6) +* searching for tags: Tag searches. (line 6) * section-numbers: Export options. (line 25) * setting tags: Setting tags. (line 6) * SHELL links: External links. (line 6) @@ -5175,12 +5290,16 @@ Index * structure of document: Document structure. (line 6) * sublevels, inclusion into tags match: Tag inheritance. (line 6) * sublevels, inclusion into todo list: Global TODO list. (line 31) +* subscript: Subscripts and Superscripts. + (line 6) * subtree cycling: Visibility cycling. (line 10) * subtree visibility states: Visibility cycling. (line 10) * subtree, cut and paste: Structure editing. (line 6) * subtree, subtree visibility state: Visibility cycling. (line 10) * subtrees, cut and paste: Structure editing. (line 6) * summary: Summary. (line 6) +* superscript: Subscripts and Superscripts. + (line 6) * syntax, of formulas: Formula syntax. (line 6) * table editor, builtin: Built-in table editor. (line 6) @@ -5196,10 +5315,14 @@ Index * tags: Tags. (line 6) * tags view: Matching headline tags. (line 6) +* tags, setting: Setting tags. (line 6) +* targets, for links: Internal links. (line 6) +* targets, radio: Radio targets. (line 6) * tasks, breaking down: Breaking down tasks. (line 6) * templates, for remember: Remember. (line 23) * TeX interpretation: Embedded LaTeX. (line 6) -* TeX macros: Export options. (line 25) +* TeX macros <1>: Export options. (line 25) +* TeX macros: Math symbols. (line 6) * TeX macros, export: Enhancing text. (line 18) * TeX symbol completion: Completion. (line 6) * TeX-like syntax for sub- and superscripts: Export options. (line 25) @@ -5207,8 +5330,10 @@ Index (line 6) * time grid: Time-of-day specifications. (line 26) -* time stamps: Time stamps. (line 6) -* time, reading in minibuffer: Creating timestamps. (line 71) +* time stamps <1>: Time stamps. (line 6) +* time stamps: Timestamps. (line 6) +* time, reading in minibuffer: The date/time prompt. + (line 6) * time-of-day specification: Time-of-day specifications. (line 6) * time-sorted view: Timeline. (line 6) @@ -5260,10 +5385,12 @@ Key Index * -: Agenda commands. (line 132) * .: Agenda commands. (line 94) * :: Agenda commands. (line 112) -* <: Creating timestamps. (line 78) +* <: The date/time prompt. + (line 28) * : Agenda commands. (line 91) * <1>: Agenda commands. (line 41) -* <2>: Creating timestamps. (line 103) +* <2>: The date/time prompt. + (line 53) * : Built-in table editor. (line 64) * : Agenda commands. (line 86) @@ -5275,7 +5402,8 @@ Key Index * <4>: Plain lists. (line 37) * : Visibility cycling. (line 10) * > <1>: Agenda commands. (line 154) -* >: Creating timestamps. (line 79) +* >: The date/time prompt. + (line 29) * ^: CDLaTeX mode. (line 33) * _: CDLaTeX mode. (line 33) * `: CDLaTeX mode. (line 39) @@ -5289,8 +5417,8 @@ Key Index * C-c !: Creating timestamps. (line 21) * C-c #: Checkboxes. (line 55) * C-c $: Moving subtrees. (line 10) -* C-c %: Handling links. (line 80) -* C-c &: Handling links. (line 84) +* C-c %: Handling links. (line 81) +* C-c &: Handling links. (line 85) * C-c ' <1>: Editing/debugging formulas. (line 20) * C-c ': Built-in table editor. @@ -5448,7 +5576,8 @@ Key Index (line 89) * M-S- <2>: Plain lists. (line 59) * M-S-: Structure editing. (line 33) -* M-S- <1>: Creating timestamps. (line 100) +* M-S- <1>: The date/time prompt. + (line 50) * M-S- <2>: Built-in table editor. (line 76) * M-S- <3>: Plain lists. (line 65) @@ -5456,7 +5585,8 @@ Key Index * M-S- <1>: Checkboxes. (line 52) * M-S- <2>: Plain lists. (line 52) * M-S-: Structure editing. (line 15) -* M-S- <1>: Creating timestamps. (line 97) +* M-S- <1>: The date/time prompt. + (line 47) * M-S- <2>: Built-in table editor. (line 79) * M-S- <3>: Plain lists. (line 65) @@ -5466,7 +5596,8 @@ Key Index * M-S- <2>: Plain lists. (line 59) * M-S-: Structure editing. (line 30) * mouse-1 <1>: Agenda commands. (line 35) -* mouse-1 <2>: Creating timestamps. (line 82) +* mouse-1 <2>: The date/time prompt. + (line 32) * mouse-1: Handling links. (line 72) * mouse-2 <1>: Agenda commands. (line 35) * mouse-2: Handling links. (line 72) @@ -5483,23 +5614,31 @@ Key Index * S: Agenda commands. (line 189) * s: Agenda commands. (line 83) * S- <1>: Agenda commands. (line 132) -* S- <2>: Creating timestamps. (line 58) -* S- <3>: Priorities. (line 25) +* S- <2>: The date/time prompt. + (line 41) +* S- <3>: Creating timestamps. (line 58) +* S- <4>: Priorities. (line 25) * S-: Plain lists. (line 55) * S- <1>: Agenda commands. (line 150) -* S- <2>: Creating timestamps. (line 53) +* S- <2>: The date/time prompt. + (line 38) +* S- <3>: Creating timestamps. (line 53) * S-: TODO basics. (line 20) * S-: Built-in table editor. (line 170) * S- <1>: Agenda commands. (line 142) -* S- <2>: Creating timestamps. (line 53) +* S- <2>: The date/time prompt. + (line 35) +* S- <3>: Creating timestamps. (line 53) * S-: TODO basics. (line 20) * S- <1>: Built-in table editor. (line 61) * S-: Visibility cycling. (line 22) * S- <1>: Agenda commands. (line 126) -* S- <2>: Creating timestamps. (line 58) -* S- <3>: Priorities. (line 25) +* S- <2>: The date/time prompt. + (line 44) +* S- <3>: Creating timestamps. (line 58) +* S- <4>: Priorities. (line 25) * S-: Plain lists. (line 55) * T: Agenda commands. (line 107) * t: Agenda commands. (line 103) @@ -5511,149 +5650,153 @@ Key Index  Tag Table: Node: Top964 -Node: Introduction10124 -Node: Summary10539 -Node: Installation12806 -Node: Activation14184 -Node: Feedback15433 -Node: Document structure16202 -Node: Outlines16976 -Node: Headlines17636 -Node: Visibility cycling18259 -Ref: Visibility cycling-Footnote-119734 -Ref: Visibility cycling-Footnote-219792 -Node: Motion19842 -Node: Structure editing20626 -Node: Archiving22735 -Node: ARCHIVE tag23293 -Node: Moving subtrees25086 -Node: Sparse trees26127 -Ref: Sparse trees-Footnote-128258 -Ref: Sparse trees-Footnote-228350 -Node: Plain lists28465 -Ref: Plain lists-Footnote-131990 -Ref: Plain lists-Footnote-232347 -Node: Tables32529 -Node: Built-in table editor33077 -Node: Narrow columns40685 -Ref: Narrow columns-Footnote-142624 -Node: Table calculations42670 -Node: Formula syntax43990 -Ref: Formula syntax-Footnote-146895 -Node: Lisp formulas47195 -Node: Column formulas47984 -Node: Advanced features49746 -Node: Named-field formulas53000 -Node: Editing/debugging formulas53640 -Node: Appetizer55398 -Node: orgtbl-mode56501 -Node: table.el56992 -Node: Hyperlinks57969 -Node: Link format58674 -Node: Internal links59967 -Ref: Internal links-Footnote-161956 -Node: Radio targets62088 -Node: CamelCase links62803 -Node: External links63301 -Node: Handling links65432 -Ref: Handling links-Footnote-170018 -Node: Search options70255 -Ref: Search options-Footnote-172029 -Node: Custom searches72110 -Node: Remember73158 -Node: TODO items76848 -Node: TODO basics77830 -Node: TODO extensions79357 -Node: Workflow states80152 -Node: TODO types81020 -Ref: TODO types-Footnote-182678 -Node: Per file keywords82760 -Ref: Per file keywords-Footnote-184214 -Node: Priorities84415 -Node: Breaking down tasks85659 -Ref: Breaking down tasks-Footnote-186179 -Node: Checkboxes86275 -Node: Timestamps89011 -Node: Time stamps89401 -Node: Creating timestamps92498 -Node: Progress logging95844 -Node: Closing items96374 -Node: Clocking work time97278 -Ref: Clocking work time-Footnote-1100841 -Node: Tags100967 -Node: Tag inheritance101729 -Node: Setting tags102666 -Ref: Setting tags-Footnote-1105798 -Ref: Setting tags-Footnote-2105910 -Node: Tag searches105990 -Node: Agenda views107199 -Node: Agenda files109088 -Ref: Agenda files-Footnote-1110048 -Ref: Agenda files-Footnote-2110197 -Node: Agenda dispatcher110390 -Node: Weekly/Daily agenda112007 -Node: Calendar/Diary integration112972 -Node: Global TODO list114310 -Node: Matching headline tags116362 -Node: Timeline117306 -Node: Presentation and sorting117969 -Node: Categories118747 -Node: Time-of-day specifications119411 -Node: Sorting of agenda items121389 -Node: Agenda commands122671 -Node: Custom agenda views128559 -Node: Storing searches129234 -Node: Block agenda131146 -Node: Setting Options132376 -Node: Batch processing135088 -Node: Embedded LaTeX136218 -Ref: Embedded LaTeX-Footnote-1137310 -Node: Math symbols137500 -Node: Subscripts and Superscripts138265 -Node: LaTeX fragments139109 -Ref: LaTeX fragments-Footnote-1141217 -Node: Processing LaTeX fragments141479 -Node: CDLaTeX mode142425 -Ref: CDLaTeX mode-Footnote-1144909 -Node: Exporting145057 -Node: ASCII export146371 -Node: HTML export147661 -Node: XOXO export150497 -Node: iCalendar export150936 -Node: Text interpretation152759 -Node: Comment lines153238 -Node: Enhancing text153709 -Node: Export options155401 -Node: Publishing157068 -Ref: Publishing-Footnote-1157864 -Node: Configuration158060 -Node: Project alist158778 -Node: Sources and destinations159844 -Node: Selecting files160574 -Node: Publishing action161322 -Node: Publishing options162555 -Node: Publishing links164707 -Node: Project page index166220 -Node: Sample configuration166998 -Node: Simple example167490 -Node: Complex example168163 -Node: Triggering publication170239 -Node: Miscellaneous170924 -Node: Completion171558 -Node: Customization172939 -Node: In-buffer settings173524 -Node: The very busy C-c C-c key176755 -Node: Clean view178399 -Node: TTY keys180976 -Node: Interaction182585 -Node: Cooperation182982 -Node: Conflicts184849 -Node: Bugs186441 -Node: Extensions and Hacking188064 -Node: Extensions188550 -Node: Dynamic blocks190120 -Node: History and Acknowledgments192047 -Node: Index197009 -Node: Key Index221368 +Node: Introduction10239 +Node: Summary10654 +Node: Installation12921 +Node: Activation14299 +Node: Feedback15548 +Node: Document structure16317 +Node: Outlines17091 +Node: Headlines17751 +Node: Visibility cycling18374 +Ref: Visibility cycling-Footnote-119849 +Ref: Visibility cycling-Footnote-219907 +Node: Motion19957 +Node: Structure editing20741 +Node: Archiving22850 +Node: ARCHIVE tag23408 +Node: Moving subtrees25201 +Node: Sparse trees26242 +Ref: Sparse trees-Footnote-128373 +Ref: Sparse trees-Footnote-228465 +Node: Plain lists28580 +Ref: Plain lists-Footnote-132105 +Ref: Plain lists-Footnote-232462 +Node: Tables32644 +Node: Built-in table editor33192 +Node: Narrow columns40800 +Ref: Narrow columns-Footnote-142739 +Node: Table calculations42785 +Node: Formula syntax44105 +Ref: Formula syntax-Footnote-147010 +Node: Lisp formulas47310 +Node: Column formulas48099 +Node: Advanced features49861 +Node: Named-field formulas53115 +Node: Editing/debugging formulas53755 +Node: Appetizer55513 +Node: orgtbl-mode56616 +Node: table.el57107 +Node: Hyperlinks58084 +Node: Link format58857 +Node: Internal links60150 +Ref: Internal links-Footnote-162139 +Node: Radio targets62271 +Node: CamelCase links62986 +Node: External links63580 +Node: Handling links65711 +Ref: Handling links-Footnote-170363 +Ref: Handling links-Footnote-270600 +Node: Link abbreviations70674 +Node: Search options72353 +Ref: Search options-Footnote-174131 +Node: Custom searches74212 +Node: Remember75260 +Node: TODO items78950 +Node: TODO basics79932 +Node: TODO extensions81459 +Node: Workflow states82254 +Node: TODO types83122 +Ref: TODO types-Footnote-184780 +Node: Per file keywords84862 +Ref: Per file keywords-Footnote-186316 +Node: Priorities86517 +Node: Breaking down tasks87761 +Ref: Breaking down tasks-Footnote-188281 +Node: Checkboxes88377 +Node: Timestamps91113 +Node: Time stamps91503 +Node: Creating timestamps94600 +Node: The date/time prompt97143 +Ref: The date/time prompt-Footnote-198827 +Node: Progress logging98933 +Node: Closing items99463 +Node: Clocking work time100367 +Ref: Clocking work time-Footnote-1103930 +Node: Tags104056 +Node: Tag inheritance104818 +Node: Setting tags105755 +Ref: Setting tags-Footnote-1108887 +Ref: Setting tags-Footnote-2108999 +Node: Tag searches109079 +Node: Agenda views110288 +Node: Agenda files112381 +Ref: Agenda files-Footnote-1113341 +Ref: Agenda files-Footnote-2113490 +Node: Agenda dispatcher113683 +Node: Weekly/Daily agenda115300 +Node: Calendar/Diary integration116265 +Node: Global TODO list117603 +Node: Matching headline tags119655 +Node: Timeline120599 +Node: Presentation and sorting121262 +Node: Categories122040 +Node: Time-of-day specifications122704 +Node: Sorting of agenda items124682 +Node: Agenda commands125964 +Node: Custom agenda views131852 +Node: Storing searches132527 +Node: Block agenda134439 +Node: Setting Options135669 +Node: Batch processing138381 +Node: Embedded LaTeX139511 +Ref: Embedded LaTeX-Footnote-1140603 +Node: Math symbols140793 +Node: Subscripts and Superscripts141558 +Node: LaTeX fragments142402 +Ref: LaTeX fragments-Footnote-1144510 +Node: Processing LaTeX fragments144772 +Node: CDLaTeX mode145718 +Ref: CDLaTeX mode-Footnote-1148202 +Node: Exporting148350 +Node: ASCII export149664 +Node: HTML export150954 +Node: XOXO export153790 +Node: iCalendar export154229 +Node: Text interpretation156052 +Node: Comment lines156531 +Node: Enhancing text157002 +Node: Export options158694 +Node: Publishing160361 +Ref: Publishing-Footnote-1161157 +Node: Configuration161353 +Node: Project alist162071 +Node: Sources and destinations163137 +Node: Selecting files163867 +Node: Publishing action164615 +Node: Publishing options165848 +Node: Publishing links168000 +Node: Project page index169513 +Node: Sample configuration170291 +Node: Simple example170783 +Node: Complex example171456 +Node: Triggering publication173532 +Node: Miscellaneous174217 +Node: Completion174851 +Node: Customization176322 +Node: In-buffer settings176907 +Node: The very busy C-c C-c key180328 +Node: Clean view181972 +Node: TTY keys184549 +Node: Interaction186158 +Node: Cooperation186555 +Node: Conflicts188422 +Node: Bugs190014 +Node: Extensions and Hacking191637 +Node: Extensions192123 +Node: Dynamic blocks193693 +Node: History and Acknowledgments195620 +Node: Index200628 +Node: Key Index227059  End Tag Table diff --git a/org.el b/org.el index eb4722b6c..bff450119 100644 --- a/org.el +++ b/org.el @@ -5,7 +5,7 @@ ;; Author: Carsten Dominik ;; Keywords: outlines, hypermedia, calendar, wp ;; Homepage: http://www.astro.uva.nl/~dominik/Tools/org/ -;; Version: 4.50 +;; Version: 4.51 ;; ;; This file is part of GNU Emacs. ;; @@ -61,6 +61,12 @@ ;; ;; Recent changes ;; -------------- +;; Version 4.51 +;; - Link abbreviations (manual section 4.5). +;; - More control over how agenda is displayed. See the new variables +;; `org-agenda-window-setup', `org-agenda-restore-windows-after-quit'. +;; - Bug fixes. +;; ;; Version 4.50 ;; - Closing a TODO item can record an additional note. ;; See variables `org-log-done' and `org-log-note-headings'. @@ -137,7 +143,7 @@ ;;; Customization variables -(defvar org-version "4.50" +(defvar org-version "4.51" "The version number of the file org.el.") (defun org-version () (interactive) @@ -691,7 +697,8 @@ this variable requires a restart of Emacs to become effective." :group 'org-table-settings :type 'string) -(defcustom org-table-number-regexp "^[<>]?[-+^.0-9]*[0-9][-+^.0-9eEdDx()%]*$" +(defcustom org-table-number-regexp + "^\\([<>]?[-+^.0-9]*[0-9][-+^.0-9eEdDx()%]*\\|\\(0[xX]\\)?[0-9a-fA-F]+\\)$" "Regular expression for recognizing numbers in table columns. If a table column contains mostly numbers, it will be aligned to the right. If not, it will be aligned to the left. @@ -715,8 +722,8 @@ Other options offered by the customize interface are more restrictive." "^[-+]?\\([0-9]*\\.[0-9]+\\|[0-9]+\\.?[0-9]*\\)$") (const :tag "Exponential, Floating point, Integer" "^[-+]?[0-9.]+\\([eEdD][-+0-9]+\\)?$") - (const :tag "Very General Number-Like" - "^[<>]?[-+^.0-9]*[0-9][-+^.0-9eEdDx()%]*$") + (const :tag "Very General Number-Like, including hex" + "^\\([<>]?[-+^.0-9]*[0-9][-+^.0-9eEdDx()%]*\\|\\(0[xX]\\)?[0-9a-fA-F]+\\)$") (string :tag "Regexp:"))) (defcustom org-table-number-fraction 0.5 @@ -847,6 +854,26 @@ Automatically means, when TAB or RET or C-c C-c are pressed in the line." :tag "Org Link" :group 'org) +(defvar org-link-abbrev-alist-local nil + "buffer-local version of `org-link-abbrev-alist', which see. +The value of this is taken from the #+LINK lines.") +(make-variable-buffer-local 'org-link-abbrev-alist-local) + +(defcustom org-link-abbrev-alist nil + "Alist of link abbreviations. +The car of each element is a string, to be replaced at the start of a link. +The cdrs are replacement values, like (\"linkkey\" . REPLACE). Abbreviated +links in Org-mode buffers can have an optional tag after a double colon, e.g. + + [[linkkey::tag][description]] + +If REPLACE is a string, the tag will simply be appended to create the link. +If the string contains \"%s\", the tag will be inserted there. REPLACE may +also be a function that will be called with the tag as the only argument to +create the link. See the manual for examples." + :group 'org-link + :type 'alist) + (defcustom org-descriptive-links t "Non-nil means, hide link part and only show description of bracket links. Bracket links are like [[link][descritpion]]. This variable sets the initial @@ -1032,6 +1059,18 @@ another window." (const find-file-other-window) (const find-file-other-frame))))) +(defcustom org-display-internal-link-with-indirect-buffer nil + "Non-nil means, use indirect buffer to display infile links. +Activating internal links (from one location in a file to another location +in the same file) normally just jumps to the location. When the link is +activated with a C-u prefix (or with mouse-3), the link is displayed in +another window. When this option is set, the other window actually displays +an indirect buffer clone of the current buffer, to avoid any visibility +changes to the current buffer." + :group 'org-link-follow + :type 'boolean) + + (defcustom org-open-non-existing-files nil "Non-nil means, `org-open-file' will open non-existing file. When nil, an error will be generated." @@ -1627,6 +1666,54 @@ forth between agenda and calendar." :tag "Org Agenda Window Setup" :group 'org-agenda) +(defcustom org-agenda-window-setup 'reorganize-frame + "How the agenda buffer should be displayed. +Possible values for this option are: + +current-window Show agenda in the current window, keeping all other windows. +other-frame Use `switch-to-buffer-other-frame' to display agenda. +other-window Use `switch-to-buffer-other-window' to display agenda. +reorganize-frame Show only two windows on the current frame, the current + window and the agenda. Also, if the option + `org-fit-agenda-window' is set, resize the agenda window to + try to as much as possible of the buffer content. +See also the variable `org-agenda-restore-windows-after-quit'." + :group 'org-agenda-setup + :type '(choice + (const current-window) + (const other-frame) + (const other-window) + (const reorganize-frame))) + +(defcustom org-agenda-restore-windows-after-quit nil + "Non-nil means, restore window configuration open exiting agenda. +Before the window configuration is changed for displaying the agenda, +the current status is recorded. When the agenda is exited with +`q' or `x' and this option is set, the old state is restored. If +`org-agenda-window-setup' is `other-frame', the value of this +option will be ignored.." + :group 'org-agenda-setup + :type 'boolean) + +;; FIXME: I think this variable could be removed. +(defcustom org-select-agenda-window t + "Non-nil means, after creating an agenda, move cursor into Agenda window. +When nil, cursor will remain in the current window." + :group 'org-agenda-setup + :type 'boolean) + +;; FIXME: I think this variable could be removed. +(defcustom org-fit-agenda-window t + "Non-nil means, change window size of agenda to fit content. +This is only effective if `org-agenda-window-setup' is `reorganize-frame'." + :group 'org-agenda-setup + :type 'boolean) + +(defcustom org-finalize-agenda-hook nil + "Hook run just before displaying an agenda buffer." + :group 'org-agenda-setup + :type 'hook) + (defcustom org-agenda-mouse-1-follows-link nil "Non-nil means, mouse-1 on a link will follow the link in the agenda. A longer mouse click will still set point. Does not wortk on XEmacs. @@ -1639,22 +1726,6 @@ Needs to be set before org.el is loaded." :group 'org-agenda-setup :type 'boolean) -(defcustom org-select-agenda-window t - "Non-nil means, after creating an agenda, move cursor into Agenda window. -When nil, cursor will remain in the current window." - :group 'org-agenda-setup - :type 'boolean) - -(defcustom org-fit-agenda-window t - "Non-nil means, change window size of agenda to fit content." - :group 'org-agenda-setup - :type 'boolean) - -(defcustom org-finalize-agenda-hook nil - "Hook run just before displaying an agenda buffer." - :group 'org-agenda ;?????? - :type 'hook) - (defgroup org-agenda-display nil "Options concerning what to display initially in Agenda." :tag "Org Agenda Display" @@ -2415,7 +2486,11 @@ Changing this variable requires a restart of Emacs to take effect." (setq markers (concat (replace-match "" t t markers) "^"))) (if (string-match "-" markers) (setq markers (concat (replace-match "" t t markers) "-"))) - (while (>= (setq nl (1- nl)) 0) (setq body1 (concat body1 "\n?" body "*?"))) +; (while (>= (setq nl (1- nl)) 0) (setq body1 (concat body1 "\n?" body "*?"))) +; (while (>= (setq nl (1- nl)) 0) (setq body1 (concat body1 "\\(?:\n?" body "*?\\)?"))) + (if (> nl 0) + (setq body1 (concat body1 "\\(?:\n" body "*?\\)\\{0," + (int-to-string nl) "\\}"))) ;; Make the regexp (setq org-emph-re (concat "\\([" pre (if stacked markers) "]\\|^\\)" @@ -2859,9 +2934,9 @@ Also put tags into group 4 if tags are present.") (when (org-mode-p) (let ((re (org-make-options-regexp '("CATEGORY" "SEQ_TODO" "PRI_TODO" "TYP_TODO" - "STARTUP" "ARCHIVE" "TAGS" "CALC"))) + "STARTUP" "ARCHIVE" "TAGS" "LINK"))) (splitre "[ \t]+") - kwds int key value cat arch tags) + kwds int key value cat arch tags links tmp) (save-excursion (save-restriction (widen) @@ -2884,6 +2959,11 @@ Also put tags into group 4 if tags are present.") kwds (append kwds (org-split-string value splitre)))) ((equal key "TAGS") (setq tags (append tags (org-split-string value splitre)))) + ((equal key "LINK") + (when (string-match "^\\(\\S-+\\)[ \t]+\\(.+\\)" value) + (push (cons (match-string 1 value) + (org-trim (match-string 2 value))) + links))) ((equal key "STARTUP") (let ((opts (org-split-string value splitre)) l var val) @@ -2900,6 +2980,7 @@ Also put tags into group 4 if tags are present.") (and kwds (org-set-local 'org-todo-keywords kwds)) (and arch (org-set-local 'org-archive-location arch)) (and int (org-set-local 'org-todo-interpretation int)) + (and links (setq org-link-abbrev-alist-local (nreverse links))) (when tags (let (e tgs) (while (setq e (pop tags)) @@ -3455,7 +3536,10 @@ between words." (list (concat "\\<" org-closed-string) '(0 'org-special-keyword t)) (list (concat "\\<" org-clock-string) '(0 'org-special-keyword t)) ;; Emphasis - (if em '(org-do-emphasis-faces)) + (if em + (if (featurep 'xemacs) + '(org-do-emphasis-faces (0 nil append)) + '(org-do-emphasis-faces))) ;; Checkboxes, similar to Frank Ruell's org-checklet.el '("^[ \t]*\\([-+*]\\|[0-9]+[.)]\\) +\\(\\[[ X]\\]\\)" 2 'bold prepend) @@ -4381,7 +4465,7 @@ with the current numbers. With optional prefix argument ALL, do this for the whole buffer." (interactive "P") (save-excursion - (let* ((buffer-invisibility-spec nil) + (let* ((buffer-invisibility-spec nil) ; Emacs 21 compatibility (beg (progn (outline-back-to-heading) (point))) (end (move-marker (make-marker) (progn (outline-next-heading) (point)))) @@ -4933,6 +5017,7 @@ the children that do not contain any open TODO items." (defvar org-agenda-multi nil) ; dynammically scoped (defvar org-agenda-buffer-name "*Org Agenda*") +(defvar org-pre-agenda-window-conf nil) (defun org-prepare-agenda () (if org-agenda-multi (progn @@ -4943,10 +5028,21 @@ the children that do not contain any open TODO items." (narrow-to-region (point) (point-max))) (org-agenda-maybe-reset-markers 'force) (org-prepare-agenda-buffers (org-agenda-files)) - (unless (equal (current-buffer) (get-buffer org-agenda-buffer-name)) - (delete-other-windows) - (switch-to-buffer-other-window - (get-buffer-create org-agenda-buffer-name))) + (let* ((abuf (get-buffer-create org-agenda-buffer-name)) + (awin (get-buffer-window abuf))) + (cond + ((equal (current-buffer) abuf) nil) + (awin (select-window awin)) + ((not (setq org-pre-agenda-window-conf (current-window-configuration)))) + ((equal org-agenda-window-setup 'current-window) + (switch-to-buffer abuf)) + ((equal org-agenda-window-setup 'other-window) + (switch-to-buffer-other-window abuf)) + ((equal org-agenda-window-setup 'other-frame) + (switch-to-buffer-other-frame abuf)) + ((equal org-agenda-window-setup 'reorganize-frame) + (delete-other-windows) + (switch-to-buffer-other-window abuf)))) (setq buffer-read-only nil) (erase-buffer) (org-agenda-mode)) @@ -5163,6 +5259,7 @@ At all other locations, this simply calls `ispell-complete-word'." (camel (equal (char-before beg) ?*)) (tag (equal (char-before beg1) ?:)) (texp (equal (char-before beg) ?\\)) + (link (equal (char-before beg) ?\[)) (opt (equal (buffer-substring (max (point-at-bol) (- beg 2)) beg) "#+")) @@ -5181,6 +5278,8 @@ At all other locations, this simply calls `ispell-complete-word'." (startup (setq type :startup) org-startup-options) + (link (append org-link-abbrev-alist-local + org-link-abbrev-alist)) (texp (setq type :tex) org-html-entities) @@ -5382,7 +5481,7 @@ be removed." (format-time-string (car org-time-stamp-formats) time)) (setq what nil)) (save-excursion - (let (col list elt (buffer-invisibility-spec nil) ts) + (let (col list elt ts buffer-invisibility-spec) (org-back-to-heading t) (looking-at (concat outline-regexp "\\( *\\)[^\r\n]*")) (goto-char (match-end 1)) @@ -5739,7 +5838,7 @@ While prompting, a calendar is popped up - you can also select the date with the mouse (button 1). The calendar shows a period of three months. To scroll it to other months, use the keys `>' and `<'. If you don't like the calendar, turn it off with - \(setq org-popup-calendar-for-date-prompt nil) + \(setq org-popup-calendar-for-date-prompt Nil) With optional argument TO-TIME, the date will immediately be converted to an internal time. @@ -6696,7 +6795,7 @@ The following commands are available: "--" ["Show" org-agenda-show t] ["Go To (other window)" org-agenda-goto t] - ["Go To (one window)" org-agenda-switch-to t] + ["Go To (this window)" org-agenda-switch-to t] ["Follow Mode" org-agenda-follow-mode :style toggle :selected org-agenda-follow-mode :active t] "--" @@ -6893,7 +6992,6 @@ L Timeline for current buffer C Configure custom agenda commands") (t (error "Invalid key")))))) ;; FIXME: what is the meaning of WINDOW????? -;; FIXME: need to force KEEP-MODES for series comands...... (defun org-run-agenda-series (series &optional window) (org-prepare-agenda) (let* ((org-agenda-multi t) @@ -6947,6 +7045,7 @@ before running the agenda command." (defun org-fit-agenda-window () "Fit the window to the buffer size." (and org-fit-agenda-window + (memq org-agenda-window-setup '(reorganize-frame)) (fboundp 'fit-window-to-buffer) (fit-window-to-buffer nil (/ (* (frame-height) 3) 4) (/ (frame-height) 2)))) @@ -7054,7 +7153,7 @@ When a buffer is unmodified, it is just killed. When modified, it is saved (with-current-buffer buf (save-buffer))) (kill-buffer buf)))) -(defun org-timeline (&optional include-all keep-modes) +(defun org-timeline (&optional include-all) "Show a time-sorted view of the entries in the current org file. Only entries with a time stamp of today or later will be listed. With \\[universal-argument] prefix, all unfinished TODO items will also be shown, @@ -7068,7 +7167,6 @@ dates." (let* ((dopast t) (dotodo include-all) (doclosed org-agenda-show-log) - (org-agenda-keep-modes keep-modes) (entry buffer-file-name) (date (calendar-current-date)) (win (selected-window)) @@ -7085,7 +7183,7 @@ dates." (setq org-agenda-redo-command (list 'progn (list 'switch-to-buffer-other-window (current-buffer)) - (list 'org-timeline (list 'quote include-all) t))) + (list 'org-timeline (list 'quote include-all)))) (if (not dopast) ;; Remove past dates from the list of dates. (setq day-numbers (delq nil (mapcar (lambda(x) @@ -7140,7 +7238,7 @@ dates." "The arguments of the previous call to org-agenda") ;;;###autoload -(defun org-agenda-list (&optional include-all start-day ndays keep-modes) +(defun org-agenda-list (&optional include-all start-day ndays) "Produce a weekly view from all files in variable `org-agenda-files'. The view will be for the current week, but from the overview buffer you will be able to go to other weeks. @@ -7156,9 +7254,8 @@ NDAYS defaults to `org-agenda-ndays'." (if org-agenda-overriding-arguments (setq include-all (car org-agenda-overriding-arguments) start-day (nth 1 org-agenda-overriding-arguments) - ndays (nth 2 org-agenda-overriding-arguments) - keep-modes (nth 3 org-agenda-overriding-arguments))) - (setq org-agenda-last-arguments (list include-all start-day ndays keep-modes)) + ndays (nth 2 org-agenda-overriding-arguments))) + (setq org-agenda-last-arguments (list include-all start-day ndays)) (org-compile-prefix-format 'agenda) (org-set-sorting-strategy 'agenda) (require 'calendar) @@ -7166,7 +7263,6 @@ NDAYS defaults to `org-agenda-ndays'." (if (or (equal ndays 1) (and (null ndays) (equal 1 org-agenda-ndays))) nil org-agenda-start-on-weekday)) - (org-agenda-keep-modes keep-modes) (thefiles (org-agenda-files)) (files thefiles) (win (selected-window)) @@ -7181,10 +7277,10 @@ NDAYS defaults to `org-agenda-ndays'." (d (- nt n1))) (- sd (+ (if (< d 0) 7 0) d))))) (day-numbers (list start)) - (inhibit-redisplay t) +;FIXME (inhibit-redisplay t) s e rtn rtnall file date d start-pos end-pos todayp nd) (setq org-agenda-redo-command - (list 'org-agenda-list (list 'quote include-all) start-day ndays t)) + (list 'org-agenda-list (list 'quote include-all) start-day ndays)) ;; Make the list of days (setq ndays (or ndays org-agenda-ndays) nd ndays) @@ -7277,7 +7373,7 @@ NDAYS defaults to `org-agenda-ndays'." (defvar org-select-this-todo-keyword nil) ;;;###autoload -(defun org-todo-list (arg &optional keep-modes) +(defun org-todo-list (arg) "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 @@ -7286,8 +7382,7 @@ for a keyword. A numeric prefix directly selects the Nth keyword in (interactive "P") (org-compile-prefix-format 'todo) (org-set-sorting-strategy 'todo) - (let* ((org-agenda-keep-modes keep-modes) - (today (time-to-days (current-time))) + (let* ((today (time-to-days (current-time))) (date (calendar-gregorian-from-absolute today)) (win (selected-window)) (kwds org-todo-keywords) @@ -7306,7 +7401,7 @@ for a keyword. A numeric prefix directly selects the Nth keyword in (org-set-local 'last-arg arg) (org-set-local 'org-todo-keywords kwds) (setq org-agenda-redo-command - '(org-todo-list (or current-prefix-arg last-arg) t)) + '(org-todo-list (or current-prefix-arg last-arg))) (setq files (org-agenda-files) rtnall nil) (while (setq file (pop files)) @@ -7366,7 +7461,12 @@ If ERROR is non-nil, throw an error, otherwise just return nil." (let ((buf (current-buffer))) (if (not (one-window-p)) (delete-window)) (kill-buffer buf) - (org-agenda-maybe-reset-markers 'force))) + (org-agenda-maybe-reset-markers 'force)) + ;; Maybe restore the pre-agenda window configuration. + (and org-agenda-restore-windows-after-quit + (not (eq org-agenda-window-setup 'other-frame)) + org-pre-agenda-window-conf + (set-window-configuration org-pre-agenda-window-conf))) (defun org-agenda-exit () "Exit agenda by removing the window or the buffer. @@ -7388,7 +7488,8 @@ Org-mode buffers visited directly by the user will not be touched." "Rebuild Agenda. When this is the global TODO list, a prefix argument will be interpreted." (interactive) - (let* ((line (org-current-line)) + (let* ((org-agenda-keep-modes t) + (line (org-current-line)) (window-line (- line (org-current-line (window-start))))) (message "Rebuilding agenda buffer...") (eval org-agenda-redo-command) @@ -8589,7 +8690,7 @@ and by additional input from the age of a schedules or deadline entry." (org-flag-heading nil)))) ; show the next heading (and highlight (org-highlight (point-at-bol) (point-at-eol))))) -(defun org-agenda-switch-to () +(defun org-agenda-switch-to (&optional delete-other-windows) "Go to the Org-mode file which contains the item at point." (interactive) (let* ((marker (or (get-text-property (point) 'org-marker) @@ -8597,7 +8698,7 @@ and by additional input from the age of a schedules or deadline entry." (buffer (marker-buffer marker)) (pos (marker-position marker))) (switch-to-buffer buffer) - (delete-other-windows) + (and delete-other-windows (delete-other-windows)) (widen) (goto-char pos) (when (org-mode-p) @@ -9018,7 +9119,7 @@ This is a command that has to be installed in `calendar-mode-map'." (interactive) (org-agenda-list nil (calendar-absolute-from-gregorian (calendar-cursor-to-date)) - nil t)) + nil)) (defun org-agenda-convert-date () (interactive) @@ -9166,14 +9267,13 @@ MATCH can contain positive and negative selection of tags, like (cons match0 matcher))) ;;;###autoload -(defun org-tags-view (&optional todo-only match keep-modes) +(defun org-tags-view (&optional todo-only match) "Show all headlines for all `org-agenda-files' matching a TAGS criterion. The prefix arg TODO-ONLY limits the search to TODO entries." (interactive "P") (org-compile-prefix-format 'tags) (org-set-sorting-strategy 'tags) - (let* ((org-agenda-keep-modes keep-modes) - (org-tags-match-list-sublevels + (let* ((org-tags-match-list-sublevels (if todo-only t org-tags-match-list-sublevels)) (win (selected-window)) (completion-ignore-case t) @@ -9184,7 +9284,7 @@ The prefix arg TODO-ONLY limits the search to TODO entries." (org-prepare-agenda) (setq org-agenda-redo-command (list 'org-tags-view (list 'quote todo-only) - (list 'if 'current-prefix-arg nil match) t)) + (list 'if 'current-prefix-arg nil match))) (setq files (org-agenda-files) rtnall nil) (while (setq file (pop files)) @@ -9263,7 +9363,6 @@ With prefix ARG, realign all tags in headings in the current buffer." nil nil current 'org-tags-history)))) (while (string-match "[-+&]+" tags) (setq tags (replace-match ":" t t tags)))) - (unless (setq empty (string-match "\\`[\t ]*\\'" tags)) (unless (string-match ":$" tags) (setq tags (concat tags ":"))) (unless (string-match "^:" tags) (setq tags (concat ":" tags)))) @@ -9284,14 +9383,15 @@ With prefix ARG, realign all tags in headings in the current buffer." (if (= (char-after) ?\ ) (forward-char 1)) (and (re-search-forward "[ \t]+$" (point-at-eol) t) (replace-match ""))) - (move-to-column (max (current-column) - (if (> org-tags-column 0) - org-tags-column - (- (- org-tags-column) (length tags)))) - t) + (let (buffer-invisibility-spec) ; Emacs 21 compatibility + (move-to-column (max (current-column) + (if (> org-tags-column 0) + org-tags-column + (- (- org-tags-column) (length tags)))) + t)) (insert tags) (if (and (not invis) (org-invisible-p)) - (outline-flag-region (point-at-bol) (point) nil))) + (outline-flag-region (point) (point-at-bol) nil))) ; show (move-to-column col)))) (defun org-tags-completion-function (string predicate &optional flag) @@ -9522,6 +9622,7 @@ the window configuration before `org-open-at-point' was called using: "The window configuration before following a link. This is saved in case the need arises to restore it.") +;; FIXME: IN-EMACS is used for many purposes, maybe rename this argument??? (defun org-open-at-point (&optional in-emacs) "Open link at or after point. If there is no link at point, this function will search forward up to @@ -9544,6 +9645,7 @@ optional argument IN-EMACS is non-nil, Emacs will visit the file." (setq link (org-link-unescape (org-match-string-no-properties 1))) (while (string-match " *\n *" link) (setq link (replace-match " " t t link))) + (setq link (org-link-expand-abbrev link)) (if (string-match org-link-re-with-space2 link) (setq type (match-string 1 link) path (match-string 2 link)) @@ -9621,7 +9723,10 @@ optional argument IN-EMACS is non-nil, Emacs will visit the file." (org-tags-view in-emacs path)) ((or (string= type "camel") (string= type "thisfile")) - (org-mark-ring-push) + (if in-emacs + (switch-to-buffer-other-window + (org-get-buffer-for-internal-link (current-buffer))) + (org-mark-ring-push)) (org-link-search path (cond ((equal in-emacs '(4)) 'occur) @@ -9716,6 +9821,24 @@ optional argument IN-EMACS is non-nil, Emacs will visit the file." (t (browse-url-at-point)))))) + +(defun org-link-expand-abbrev (link) + "Apply replacements as defined in `org-link-abbrev-alist." + (if (string-match "^\\([a-zA-Z]+\\)\\(::\\(.*\\)\\)?$" link) + (let* ((key (match-string 1 link)) + (as (or (assoc key org-link-abbrev-alist-local) + (assoc key org-link-abbrev-alist))) + (tag (and (match-end 2) (match-string 3 link))) + rpl) + (if (not as) + link + (setq rpl (cdr as)) + (cond + ((symbolp rpl) (funcall rpl tag)) + ((string-match "%s" rpl) (replace-match (or tag "") t t rpl)) + (t (concat rpl tag))))) + link)) + (defun org-link-search (s &optional type) "Search for a link search option. When S is a CamelCaseWord, search for a target, or for a sentence containing @@ -9817,6 +9940,22 @@ in all files." (throw 'exit (point))) (goto-char (match-end 0))))))) +(defun org-get-buffer-for-internal-link (buffer) + "Return a buffer to be used for displaying the link target of internal links." + (cond + ((not org-display-internal-link-with-indirect-buffer) + buffer) + ((string-match "(Clone)$" (buffer-name buffer)) + (message "Buffer is already a clone, not making another one") + ;; we also do not modify visibility in this case + buffer) + (t ; make a new indirect buffer for displaying the link + (let* ((bn (buffer-name buffer)) + (ibn (concat bn "(Clone)")) + (ib (or (get-buffer ibn) (make-indirect-buffer buffer ibn 'clone)))) + (with-current-buffer ib (org-overview)) + ib)))) + (defun org-do-occur (regexp &optional cleanup) "Call the Emacs command `occur'. If CLEANUP is non-nil, remove the printout of the regular expression @@ -10300,7 +10439,7 @@ on the system \"/user@host:\"." ((fboundp 'tramp-handle-file-remote-p) (tramp-handle-file-remote-p file)) ((and (boundp 'ange-ftp-name-format) - (string-match ange-ftp-name-format file)) + (string-match (car ange-ftp-name-format) file)) t) (t nil))) @@ -13850,6 +13989,7 @@ translations. There is currently no way for users to extend this.") (message "Exporting...") ;; Normalize links: Convert angle and plain links into bracket links + ;; Expand link abbreviations (goto-char (point-min)) (while (re-search-forward re-plain-link nil t) (replace-match @@ -13862,6 +14002,11 @@ translations. There is currently no way for users to extend this.") (concat (match-string 1) "[[" (match-string 2) ":" (match-string 3) "]]") t t)) + (goto-char (point-min)) + (while (re-search-forward "\\[\\[\\([^]]+\\)\\]" nil t) + (replace-match (concat "[[" (save-match-data + (org-link-expand-abbrev (match-string 1))) + "]"))) ;; Find multiline emphasis and put them into single line (when (memq :emph-multiline parameters) @@ -16948,9 +17093,10 @@ Show the heading too, if it is currently invisible." ; (progn (outline-end-of-heading) (point)) ; nil)))) -;;; Finish up +;;; Finish up + (provide 'org) (run-hooks 'org-load-hook) diff --git a/org.pdf b/org.pdf index b0ae9c349..f32ae3ff5 100644 Binary files a/org.pdf and b/org.pdf differ diff --git a/org.texi b/org.texi index d94bc6d87..7f59d3454 100644 --- a/org.texi +++ b/org.texi @@ -3,7 +3,7 @@ @setfilename ../info/org @settitle Org Mode Manual -@set VERSION 4.50 +@set VERSION 4.51 @set DATE September 2006 @dircategory Emacs @@ -142,6 +142,7 @@ Hyperlinks * Internal links:: Links to other places in the current file * External links:: URL-like links to the world * Handling links:: Creating, inserting and following +* Link abbreviations:: Shortcuts for writing complex links * Search options:: Linking to a specific location * Custom searches:: When the default search is not enough * Remember:: Org-trees store quick notes @@ -171,6 +172,10 @@ Timestamps * Creating timestamps:: Commands which insert timestamps * Progress logging:: Documenting when what work was done. +Creating timestamps + +* The date/time prompt:: + Progress Logging * Closing items:: When was this entry marked DONE? @@ -1601,6 +1606,7 @@ links to other files, Usenet articles, emails, and much more. * Internal links:: Links to other places in the current file * External links:: URL-like links to the world * Handling links:: Creating, inserting and following +* Link abbreviations:: Shortcuts for writing complex links * Search options:: Linking to a specific location * Custom searches:: When the default search is not enough * Remember:: Org-trees store quick notes @@ -1641,6 +1647,7 @@ internal structure of all links, use the menu entry @cindex internal links @cindex links, internal @cindex CamelCase links +@cindex targets, for links If the link does not look like a URL, it is considered to be internal in the current file. Links such as @samp{[[My Target]]} or @samp{[[My @@ -1691,6 +1698,9 @@ earlier. @node Radio targets, CamelCase links, Internal links, Internal links @subsection Radio targets +@cindex radio targets +@cindex targets, radio +@cindex links, radio targets You can configure Org-mode to link any occurrences of certain target names in normal text. So without explicitly creating a link, the text @@ -1709,10 +1719,11 @@ loaded into Emacs. To update the target list during editing, press Org-mode also supports CamelCase words as links. This feature is not turned on by default because of the inconsistencies this system suffers -from. To activate CamelCase words as links, you need to customize -the option @code{org-activate-links}. A CamelCase word then leads to a -text search such that @samp{CamelCaseLink} is equivalent to -@samp{[[camel case link]]}. +from. It is also possible that this feature will disappear entirely in +a future version of Org-mode. To activate CamelCase words as links, you +need to customize the option @code{org-activate-links}. A CamelCase +word then leads to a text search such that @samp{CamelCaseLink} is +equivalent to @samp{[[camel case link]]}. @node External links, Handling links, Internal links, Hyperlinks @section External links @@ -1775,8 +1786,9 @@ as links. If spaces must be part of the link (for example in @samp{bbdb:Richard Stallman}), or you need to remove ambiguities about the end of the link, enclose them in angular brackets. -@node Handling links, Search options, External links, Hyperlinks +@node Handling links, Link abbreviations, External links, Hyperlinks @section Handling links +@cindex links, handling Org-mode provides methods to create a link in the correct syntax, to insert it into an org-mode file, and to follow the link. @@ -1865,7 +1877,9 @@ would. Under Emacs 22, also @kbd{mouse-1} will follow a link. @kindex mouse-3 @item mouse-3 -Like @kbd{mouse-2}, but force file links to be opened with Emacs. +Like @kbd{mouse-2}, but force file links to be opened with Emacs, and +internal links to be displayed in another window@footnote{See the +variable @code{org-display-internal-link-with-indirect-buffer}}. @cindex mark ring @kindex C-c % @@ -1882,8 +1896,57 @@ command several times in direct succession moves through a ring of previously recorded positions. @end table +@node Link abbreviations, Search options, Handling links, Hyperlinks +@section Link abbreviatons +@cindex link abbreviations +@cindex abbreviation, links -@node Search options, Custom searches, Handling links, Hyperlinks +Long URLs can be cumbersome to type, and often many similar links are +needed in a document. For this you can use link abbreviations. An +abbreviated link looks like this + +@example +[[linkword::tag][description]] +@end example + +@noindent +where the tag is optional. Such abbreviations are resolved according to +the information in the variable @code{org-link-abbrev-alist} that +relates the linkwords to replacement text. Here is an example: + +@lisp +@group +(setq org-link-abbrev-alist + '(("bugzilla" . "http://10.1.2.9/bugzilla/show_bug.cgi?id=") + ("google" . "http://www.google.com/search?q=") + ("ads" . "http://adsabs.harvard.edu/cgi-bin/ + nph-abs_connect?author=%s&db_key=AST"))) +@end group +@end lisp + +If the replacement text contains the string @samp{%s}, it will be +replaced with the tag. Otherwise the tag will be appended to the string +in order to create the link. You may also specify a function that will +be called with the tag as the only argument to create the link. + +With the above setting, you could link to a specific bug with +@code{[[bugzilla::129]]}, search the web for OrgMode with +@code{[[google::OrgMode]]} and find out what the Org-mode author is +doing besides Emacs hacking with @code{[[ads::Dominik,C]]}. + +If you need special abbreviations just for a single Org-mode buffer, you +can define them in the file with + +@example +#+LINK: bugzilla http://10.1.2.9/bugzilla/show_bug.cgi?id= +#+LINK: google http://www.google.com/search?q=%s +@end example + +@noindent +In-buffer completion @pxref{Completion} can be used after @samp{[} to +complete link abbreviations. + +@node Search options, Custom searches, Link abbreviations, Hyperlinks @section Search options in file links @cindex search option in file links @cindex file links, searching @@ -1935,6 +1998,7 @@ a search for @samp{find me} in the current file, just as @node Custom searches, Remember, Search options, Hyperlinks @section Custom Searches @cindex custom search strings +@cindex search strings, custom The default mechanism for creating search strings and for doing the actual search related to a file link may not work correctly in all @@ -2368,6 +2432,8 @@ back into synch. Or simply toggle any checkbox twice with @kbd{C-c C-c}. @node Timestamps, Tags, TODO items, Top @chapter Timestamps +@cindex time stamps +@cindex date stamps Items can be labeled with timestamps to make them useful for project planning. @@ -2547,15 +2613,42 @@ end. With prefix arg, insert result after the time range (in a table: into the following column). @end table + +@menu +* The date/time prompt:: +@end menu + +@node The date/time prompt, , Creating timestamps, Creating timestamps +@subsection The date/time prompt @cindex date, reading in minibuffer @cindex time, reading in minibuffer + +When Org-mode prompts for a date/time, the prompt suggests to enter an +ISO date. But it will in fact accept any string containing some date +and/or time information. You can, for example, use @kbd{C-y} to paste a +(possibly multi-line) string copied from an email message. Org-mode +will find whatever information is in there and will replace anything not +specified with the current date and time. For example: + +@example + 3-2-5 --> 2003-02-05 + feb 15 --> currentyear-02-15 + sep 12 9 --> 2009-09-12 + 12:45 --> today 12:45 + 22 sept 0:34 --> currentyear-09-22 0:34 + 12 --> currentyear-currentmonth-12 + Fri --> nearest Friday (today or later) +@end example + +The function understands English month and weekday abbreviations. If +you want to use unabbreviated names and/or other languages, configure +the variables @code{parse-time-months} and @code{parse-time-weekdays}. + @cindex calendar, for selecting date -When Org-mode prompts for a date/time, the function reading your input -will replace anything you choose not to specify with the current date -and time. For details, see the documentation string of -@command{org-read-date}. Also, a calender will pop up to allow -selecting a date. The calendar can be fully controlled from the -minibuffer, and a date can be selected with the following commands: +Parallel to the minibuffer prompt, a calendar is popped up@footnote{If +you don't need/want the calendar, configure the variable +@code{org-popup-calendar-for-date-prompt}.}. You can control the +calendar fully from the minibuffer: @table @kbd @kindex < @@ -2767,6 +2860,7 @@ searching using the variables @code{org-use-tag-inheritance} and @node Setting tags, Tag searches, Tag inheritance, Tags @section Setting tags @cindex setting tags +@cindex tags, setting @kindex M-@key{TAB} Tags can simply be typed into the buffer at the end of a headline. @@ -2858,6 +2952,7 @@ in a specific file? Just add an empty TAGS option line to that file: @node Tag searches, , Setting tags, Tags @section Tag searches @cindex tag searches +@cindex searching for tags Once a tags system has been set up, it can be used to collect related information into special lists. @@ -2924,7 +3019,12 @@ combinations of different views. The extracted information is displayed in a special @emph{agenda buffer}. This buffer is read-only, but provides commands to visit the corresponding locations in the original Org-mode files, and even to -edit these files remotely. +edit these files remotely. + +Two variables control how the agenda buffer is displayed and whether the +window configuration is restored when the agenda exits: +@code{org-agenda-window-setup} and +@code{org-agenda-restore-windows-after-quit}. @menu * Agenda files:: Files being searched for agenda information @@ -2941,6 +3041,7 @@ edit these files remotely. @node Agenda files, Agenda dispatcher, Agenda views, Agenda views @section Agenda files @cindex agenda files +@cindex files for agenda The information to be shown is collected from all @emph{agenda files}, the files listed in the variable @code{org-agenda-files}@footnote{If the @@ -3707,6 +3808,7 @@ yourself. @node Batch processing, , Setting Options, Custom agenda views @subsection Creating agenda views in batch processing +@cindex agenda, batch production If you want to print or otherwise reprocess agenda views, it can be useful to create an agenda from the command line. This is the purpose @@ -3764,6 +3866,8 @@ to do with it. @node Math symbols, Subscripts and Superscripts, Embedded LaTeX, Embedded LaTeX @section Math symbols +@cindex math symbols +@cindex TeX macros You can use La@TeX{} macros to insert special symbols like @samp{\alpha} to indicate the Greek letter, or @samp{\to} to indicate an arrow. @@ -3782,6 +3886,8 @@ into the proper syntax for HTML, for the above examples this is @node Subscripts and Superscripts, LaTeX fragments, Math symbols, Embedded LaTeX @section Subscripts and Superscripts +@cindex subscript +@cindex superscript Just like in La@TeX{}, @samp{^} and @samp{_} are used to indicate super- and subscripts. Again, these can be used without embedding them in @@ -3802,6 +3908,7 @@ are surrounded with @code{} and @code{} tags, respectively. @node LaTeX fragments, Processing LaTeX fragments, Subscripts and Superscripts, Embedded LaTeX @section LaTeX fragments +@cindex LaTeX fragments With symbols, sub- and superscripts, HTML is pretty much at its end when it comes to representing mathematical formulas@footnote{Yes, there is @@ -3852,6 +3959,7 @@ ones you do not wish to have interpreted by the La@TeX{} converter. @node Processing LaTeX fragments, CDLaTeX mode, LaTeX fragments, Embedded LaTeX @section Processing LaTeX fragments +@cindex LaTeX fragments, preview La@TeX{} fragments can be processed to produce a preview images of the typeset expressions: @@ -3880,6 +3988,7 @@ setting is active: @node CDLaTeX mode, , Processing LaTeX fragments, Embedded LaTeX @section Using CDLaTeX to enter math +@cindex CDLaTeX CDLaTeX-mode is a minor mode that is normally used in combination with a major LaTeX mode like AUCTeX in order to speed-up insertion of @@ -4706,6 +4815,8 @@ variable @code{org-tag-alist} (possibly set through the @samp{#+TAGS} in-buffer option, @pxref{Setting tags}), or it is created dynamically from all tags used in the current buffer. @item +After @samp{[}, complete link abbreviations (@pxref{Link abbreviations}). +@item After @samp{#+}, complete the special keywords like @samp{TYP_TODO} or @samp{OPTIONS} which set file-specific options for Org-mode. When the option keyword is already complete, pressing @kbd{M-@key{TAB}} again @@ -4791,6 +4902,10 @@ and @code{org-todo-interpretation}. These lines (several such lines are allowed) specify the legal tags in this file, and (potentially) the corresponding @emph{fast tag selection} keys. The corresponding variable is @code{org-tag-alist}. +@item #+LINK: linkword replace +These lines (several are allowed) specify link abbreviations. +@xref{Link abbreviations}. The corresponding variable is +@code{org-link-abbrev-alist}. @item #+CATEGORY: This line sets the category for the agenda file. The category applies for all subsequent lines until the next @samp{#+CATEGORY} line, or the @@ -4805,6 +4920,7 @@ These lines provide settings for exporting files. For more details see @node The very busy C-c C-c key, Clean view, In-buffer settings, Miscellaneous @section The very busy C-c C-c key @kindex C-c C-c +@cindex C-c C-c, overview The key @kbd{C-c C-c} has many purposes in org-mode, which are all mentioned scattered throughout this manual. One specific function of @@ -4994,7 +5110,6 @@ with other code out there. * Conflicts:: Packages that lead to conflicts @end menu - @node Cooperation, Conflicts, Interaction, Interaction @subsection Packages that Org-mode cooperates with @@ -5325,6 +5440,8 @@ Linking to VM/BBDB/GNUS was inspired by @i{Tom Shannon}'s @i{Daniel Sinder} came up with the idea of internal archiving by locking subtrees. @item +@i{Dale Smith} proposed link abbreviations. +@item @i{David O'Toole} wrote @file{org-publish.el} and drafted the manual chapter about publishing. @item diff --git a/orgcard.pdf b/orgcard.pdf index 38b09937f..9c41a27fd 100644 Binary files a/orgcard.pdf and b/orgcard.pdf differ diff --git a/orgcard.tex b/orgcard.tex index a2e183964..f72d6553c 100644 --- a/orgcard.tex +++ b/orgcard.tex @@ -1,5 +1,5 @@ % Reference Card for Org Mode -\def\orgversionnumber{4.50} +\def\orgversionnumber{4.51} \def\year{2006} % %**start of header @@ -424,10 +424,11 @@ formula, \kbd{:=} a named-field formula. \key{insert file link with file name completion}{C-u C-c C-l} \key{edit (also hidden part of) link at point}{C-c C-l} -\key{open file links in emacs (\kbd{C-u} : in emacs)}{C-c C-o} -\key{open link at point (3: in emacs)}{mouse-2/3} -%\key{open file links in emacs}{mouse-3} -%\key{record a position in mark ring}{C-c \%} +\key{open file links in emacs}{C-c C-o} +\key{...force open in emacs/other window}{C-u C-c C-o} +\key{open link at point}{mouse-1/2} +\key{...force open in emacs/other window}{mouse-3} +\key{record a position in mark ring}{C-c \%} \key{jump back to last followed link(s)}{C-c \&} {\bf Internal Links}