diff --git a/org b/org index f003931fa..51d4c2b4c 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.19b). + This manual is for Org-mode (version 4.20). 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.19b). +This manual is for Org-mode (version 4.20). Copyright (C) 2004, 2005, 2006 Free Software Foundation @@ -265,12 +265,6 @@ this: which will select Org-mode for this buffer no matter what the file's name is. See also the variable `org-insert-mode-line-in-empty-file'. - If you are upgrading to version 4.20 or later from a version 4.14 or -earlier, some links may stop working. These are links containing space -characters. To make such links work again, and also to transform all -links from the old `' format to the new `[[link]]' format, -execute once in each file: `M-x org-upgrade-old-links'. -  File: org, Node: Feedback, Prev: Installation and activation, Up: Introduction @@ -681,18 +675,16 @@ unpredictable for you, configure the variables Creation and conversion ....................... -`M-x org-table-create' - Creates an empty Org-mode table. However, it is much easier to - just start typing, like `|Name|Phone|Age |- ' - -`C-c C-c' - Convert region to table. Works when the cursor is not in an - existing table, and when there is a region defined. If every line - contains at least one TAB character, the function assumes that the - material is tab separated. If not, lines are split at whitespace - into fields. You can use a prefix argument to indicate the - minimum number of consequtive spaces required to indentify a field - separator (default: just one). +`C-c |' + Convert the active region to table. If every line contains at + least one TAB character, the function assumes that the material is + tab separated. If not, lines are split at whitespace into fields. + You can use a prefix argument to indicate the minimum number of + consequtive spaces required to indentify a field separator + (default: just one). + If there is no active region, this command creates an empty + Org-mode table. However, it's easier to just start typing, like + `|Name|Phone|Age |- '. Re-aligning and field motion ............................ @@ -834,11 +826,6 @@ Miscellaneous This is an alias for `C-u C-c `' to make the current field fully visible. -`C-c |' - Toggle the visibility of vertical lines in tables. The lines are - still there, only made invisible with a text property. Any `|' - added by hand will become invisible on the next align. - `M-x org-table-import' Import a file as a table. The table should be TAB- or whitespace separated. Useful, for example, to import an Excel table or data @@ -1236,25 +1223,27 @@ File: org, Node: Link format, Next: Internal links, Prev: Hyperlinks, Up: Hy 4.1 Link format =============== -Org-mode will recognize plain URL-like links in the buffer and activate -them as clickable links. However, the general linkformat looks like -this: +Org-mode will recognize plain URL-like links and activate them as +clickable links. However, the general linkformat looks like this: [[link][description]] or alternatively [[link]] - The description part is optional. Once a link in the buffer is -complete, Org-mode will change the display so that `description'( is -displayed instead of `[[link][description]]' and `link' is displayed -instead of `[[link]]'. Links will be highlighted in the face -`org-link', which by default is an underlined face. You can directly -edit the visible part of a link. To edit the invisible part, use `C-c -C-l' with the cursor on the link. If you place the cursor at the -beginning of end of the displayed text and press , you will -remove the (invisible) bracket at that location. This makes the link -incomplete and the internals are again displayed as plain text. -Inserting the missing bracket does hide the link internal again. -Finally, you may also use the menu entry `Org->Hperlinks->Literal -links' to unhide all links. + Once a link in the buffer is complete (all brackets present), +Org-mode will change the display so that `description' is displayed +instead of `[[link][description]]' and `link' is displayed instead of +`[[link]]'. Links will be highlighted in the face `org-link', which by +default is an underlined face. You can directly edit the visible part +of a link. Note that this can be either the `link' part (if there is +not description) or the `description' part. To edit also the invisible +`link' part, use `C-c C-l' with the cursor on the link. + + If you place the cursor at the beginning or just behind the end of +the displayed text and press , you will remove the +(invisible) bracket at that location. This makes the link incomplete +and the internals are again displayed as plain text. Inserting the +missing bracket does hide the link internals again. To show the +internal structure of all links, use the menu entry +`Org->Hyperlinks->Literal links'.  File: org, Node: Internal links, Next: External links, Prev: Link format, Up: Hyperlinks @@ -1325,13 +1314,9 @@ 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. It is mainly kept for backward compatibility, but the use is -deprecated. To activate CamelCase words as links, and to make headline -completion offer CamelCase version of headlines, the following -customization is needed: - - (setq org-activate-camels t - org-file-link-context-use-camel-case t) +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]]'.  File: org, Node: External links, Next: Managing links, Prev: Internal links, Up: Hyperlinks @@ -1360,7 +1345,7 @@ following list shows examples for each link type. gnus:group GNUS group link gnus:group#id GNUS article link bbdb:Richard Stallman BBDB link - shell:ls *.org(1) A shell command + shell:ls *.org A shell command A link should be enclosed in double brackets and may contain a descriptive text to be displayed instead of the url (*note Link @@ -1369,13 +1354,9 @@ format::), for example: [[http://www.gnu.org/software/emacs/][GNU Emacs]] Org-mode also finds external links in the normal text and activates -them as links. Plain text links cannot contain spaces. To remove -ambiguities about the end of the link, enclose them in angular brackets. - - ---------- Footnotes ---------- - - (1) Note that `<' and `>' cannot be part of a link, and therefore of -a shell command. If you need redirection, use @{ and @} instead. +them as links. If spaces must be part of the link (for example in +`bbdb:Richard Stallman') or to remove ambiguities about the end of the +link, enclose them in angular brackets.  File: org, Node: Managing links, Next: Search Options, Prev: External links, Up: Hyperlinks @@ -1390,9 +1371,9 @@ insert it into an org-mode file, and to follow the link. Store a link to the current location. This is a _global_ command which can be used in any buffer to create a link. The link will be stored for later insertion into an Org-mode buffer (see below). - For VM, RMAIL, WANDERLUST, GNUS and BBDB buffers, the link will - point to the current article/entry. For W3 and W3M buffers, the - link goes to the current URL. For Org-mode files, the current + For VM, RMAIL, WANDERLUST, MH-E, GNUS and BBDB buffers, the link + will point to the current article/entry. For W3 and W3M buffers, + the link goes to the current URL. For Org-mode files, the current headline is targeted. For any other files, the link will point to the file, with a search string (*note Search Options::) pointing to the contents of the current line. If there is an active @@ -1519,11 +1500,11 @@ location in your Org-mode outline tree. The following customization(1) will tell _Remember_ to use org files as target, and to create annotations compatible with Org-mode links. + (setq org-directory "~/path/to/my/orgfiles/") + (setq org-default-notes-file "~/.notes") (autoload 'org-remember-annotation "org") (autoload 'org-remember-apply-template "org") (autoload 'org-remember-handler "org") - (setq org-directory "~/path/to/my/orgfiles/") - (setq org-default-notes-file "~/.notes") (setq remember-annotation-functions '(org-remember-annotation)) (setq remember-handler-functions '(org-remember-handler)) (add-hook 'remember-mode-hook 'org-remember-apply-template) @@ -1538,9 +1519,9 @@ journal entries, you could use: (?j "* %U %?\n\n %i\n %a" "~/org/JOURNAL.org"))) In these entries, the character specifies how to select the template, -the first string specifies the template, and the second string -specifies a default file (overruling `org-default-notes-file') as a -target for this note. +the first string specifies the template, and the (optional) second +string specifies a default file (overruling `org-default-notes-file') +as a target for this note. When you call `M-x remember' to remember something, org will prompt for a key to select the template and then prepare the buffer like @@ -1556,14 +1537,13 @@ or See the variable `org-remember-templates' for more details. When you are finished composing a note with remember, you have to -press `C-c C-c' to exit remember-mode and to file the note away. The -handler first prompts for a target file - if you press , the value -of `org-default-notes-file' is used. Then the command offers the -headings tree of the selected file. You can either immediately press - to get the note appended to the file. Or you can use vertical -cursor motion ( and ) and visibility cycling () to find -a better place. Pressing or or leads to the -following result. +press `C-c C-c' to file the note away. The handler first prompts for a +target file - if you press , the value of `org-default-notes-file' +is used. Then the command offers the headings tree of the selected +file. You can either immediately press to get the note appended +to the file. Or you can use vertical cursor motion ( and ) +and visibility cycling () to find a better place. Pressing +or or leads to the following result. Cursor Key Note gets inserted position @@ -2532,7 +2512,7 @@ Remote editing original org file. `T' - Show all tags assiciated with the current item. Because of + Show all tags associated with the current item. Because of inheritance, this may be more than the tags listed in the line itself. @@ -2591,7 +2571,7 @@ Calendar commands date at the cursor. `M' - Show the phases of the moon for the three month around current + Show the phases of the moon for the three months around current date. `S' @@ -3049,33 +3029,53 @@ File: org, Node: FAQ, Next: Interaction, Prev: TTY keys, Up: Miscellaneous 2. Some of my links stopped working after I upgraded to a version 4.20 or later. Why is this, and how can I fix it? - The newer versions of Org-mode have a better link system and no - longer allow unescaped space characters as part of a link. To fix - these links, and also to move all `' style links to the new - `[[link]]' system, execute once in each Org-mode file: `M-x - org-upgrade-old-links'. + These must be links in plain text, containing white space, such as + `bbdb:Richard Stallman'. You need to protect these links by + putting double brackets around them, like `[[bbdb:Richard + Stallman]]'. - 3. I really like the old style links with angular brackets better. - Please give them back to me, don't tell me it is not possible! + 3. I see that Org-mode now creates links using the double bracket + convention that hides the link part and the brackets, only showing + the description part. How can I convert my old links to this new + format? + Execute once in each Org-mode file: `M-x org-upgrade-old-links'. + The replaces angular brackets with the link format. + + 4. I don't care if you find the new bracket links great, I am + attached to the old style using angular brackets and no hiding of + the link text. Please give them back to me, don't tell me it is + not possible! Would I let you down like that? If you must (even if I don't understand why), you can do this - (setq org-allow-space-in-plain-links t - org-link-style 'plain + (setq org-link-style 'plain org-link-format "<%s>") - 4. All these stars are driving me mad, I just find the Emacs outlines + 5. When I am executing shell links I always get a confirmation prompt + and need to type `yes ', thats 4 key presses! Can I get rid + of this? + The confirmation is there to protect you from unwantingly execute + potentially dangerous commands. For example, imagine a link + `[[shell:rm -rf ~/*][Google Search]]'. In an Org-mode buffer, this + command would look like `Google Search', but really it would remove + your home directory. If you wish, you can make it easier to + respond to the query by setting `org-confirm-shell-links' to + `y-or-n-p'. Then a single `y' keypress will be enough to confirm + shell links. It is also possible to turn off this check entirely, + but I do not recommend to do this. Be warned. + + 6. All these stars are driving me mad, I just find the Emacs outlines unreadable. Can't you just put white space and a single star as a starter for headlines? See *Note Clean view::. - 5. I would like to have two windows on the same Org-mode file, but + 7. I would like to have two windows on the same Org-mode file, but with different outline visibility. Is that possible? - In GNU Emacs, you may use _indirect buffers_ which do exactly - this. See the documentation on the command - `make-indirect-buffer'. In XEmacs, this is currently not possible - because of the different outline implementation. + In GNU Emacs, you may use _indirect buffers_ which do exactly this. + See the documentation on the command `make-indirect-buffer'. In + XEmacs, this is currently not possible because of the different + outline implementation. - 6. When I export my TODO list, every TODO item becomes a separate + 8. When I export my TODO list, every TODO item becomes a separate section. How do I enforce these items to be exported as an itemized list? If you plan to use ASCII or HTML export, make sure things you want @@ -3093,42 +3093,35 @@ File: org, Node: FAQ, Next: Interaction, Prev: TTY keys, Up: Miscellaneous +OPTIONS: H:2; ... - 7. I would like to export only a subtree of my file to HTML. How? + 9. I would like to export only a subtree of my file to HTML. How? If you want to export a subtree, mark the subtree as region and then export. Marking can be done with `C-c @ C-x C-x', for example. - 8. Org-mode takes over the S-cursor keys. I also want to use + 10. Org-mode takes over the S-cursor keys. I also want to use CUA-mode, is there a way to fix this conflict? Yes, see *Note Interaction::. - 9. Is there an easy way to insert an empty table template with a - default number of rows and columns? - To insert an empty table template, just type `|-' and use . - The default size can be changed with the variable - `org-table-default-size'. However, just starting to type the - first line is usually much easier. - - 10. One of my table columns has started to fill up with `#ERROR'. + 11. One of my table columns has started to fill up with `#ERROR'. What is going on? Org-mode tried to compute the column from other fields using a formula stored in the `#+TBLFMT:' line just below the table, and the evaluation of the formula fails. Fix the fields used in the formula, or fix the formula, or remove it! - 11. When I am in the last column of a table and just above a + 12. When I am in the last column of a table and just above a horizontal line in the table, pressing TAB creates a new table line before the horizontal line. How can I quickly move to the line below the horizontal line instead? Press (to get on the separator line) and then . Or configure the variable `org-table-tab-jumps-over-hlines'. - 12. How can I change the indentation of an entire table without fixing + 13. How can I change the indentation of an entire table without fixing every line by hand? The indentation of a table is set by the first line. So just fix the indentation of the first line and realign with . - 13. Is it possible to include entries from org-mode files into my + 14. Is it possible to include entries from org-mode files into my emacs diary? Since the org-mode agenda is much more powerful and can contain the diary (*note Calendar/Diary integration::), you should think twice @@ -3374,7 +3367,7 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top * active region <1>: HTML export. (line 10) * active region <2>: ASCII export. (line 6) * active region <3>: Built-in table editor. - (line 167) + (line 165) * active region: Structure editing. (line 46) * agenda: Weekly/Daily Agenda. (line 6) * agenda commands, custom: Agenda dispatcher. (line 6) @@ -3398,7 +3391,7 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top * calc.el: Interaction. (line 17) * calculations, in tables <1>: Table calculations. (line 6) * calculations, in tables: Built-in table editor. - (line 137) + (line 135) * calendar integration: Calendar/Diary integration. (line 6) * calendar, for selecting date: Creating timestamps. (line 68) @@ -3436,6 +3429,7 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top * cutting, of subtrees: Structure editing. (line 6) * cycling, of TODO states: TODO basics. (line 13) * cycling, visibility: Visibility cycling. (line 6) +* dangerous commands: FAQ. (line 37) * date stamps: Time stamps. (line 6) * date, reading in minibuffer: Creating timestamps. (line 68) * DEADLINE keyword: Time stamps. (line 27) @@ -3454,7 +3448,7 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top * emphasized text: Export options. (line 22) * evaluate time range: Creating timestamps. (line 63) * exporting: Exporting. (line 6) -* exporting a subtree: FAQ. (line 58) +* exporting a subtree: FAQ. (line 78) * exporting, not: Comment lines. (line 6) * extended TODO keywords: TODO extensions. (line 6) * external links: External links. (line 6) @@ -3479,7 +3473,7 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top (line 6) * formula, for table column: Column formulas. (line 6) * formula, in tables: Built-in table editor. - (line 137) + (line 135) * global keybindings: Installation and activation. (line 6) * global TODO list: Global TODO list. (line 6) @@ -3499,8 +3493,8 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top * HTML tags: HTML formatting. (line 33) * hyperlinks: Hyperlinks. (line 6) * iCalendar export: iCalendar export. (line 6) -* indentation, of tables: FAQ. (line 89) -* indirect buffers: FAQ. (line 34) +* indentation, of tables: FAQ. (line 102) +* indirect buffers: FAQ. (line 54) * inheritance, of tags: Tag inheritance. (line 6) * inserting links: Managing links. (line 23) * installation: Installation and activation. @@ -3523,7 +3517,7 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top * lists, plain: Plain Lists. (line 6) * logging, of progress: Progress logging. (line 6) * maintainer: Feedback. (line 6) -* make-indirect-buffer: FAQ. (line 34) +* make-indirect-buffer: FAQ. (line 54) * mark ring: Managing links. (line 72) * marking characters, tables: Advanced features. (line 34) * matching, of tags: Matching headline tags. @@ -3569,7 +3563,7 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top * region, active <1>: HTML export. (line 10) * region, active <2>: ASCII export. (line 6) * region, active <3>: Built-in table editor. - (line 167) + (line 165) * region, active: Structure editing. (line 46) * remember.el <1>: Interaction. (line 39) * remember.el: Remember. (line 6) @@ -3580,6 +3574,7 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top * section-numbers: Export options. (line 22) * setting tags: Setting tags. (line 6) * SHELL links: External links. (line 6) +* shell links, confirmation: FAQ. (line 37) * show all, command: Visibility cycling. (line 27) * show all, global visibility state: Visibility cycling. (line 19) * show hidden text: Visibility cycling. (line 6) @@ -3604,7 +3599,6 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top (line 6) * table editor, table.el: table.el. (line 6) * table of contents: Export options. (line 22) -* table, empty template: FAQ. (line 68) * table.el <1>: Interaction. (line 13) * table.el: table.el. (line 6) * tables <1>: Export options. (line 22) @@ -3636,7 +3630,7 @@ File: org, Node: Index, Next: Key Index, Prev: Miscellaneous, Up: Top * transient-mark-mode <1>: HTML export. (line 10) * transient-mark-mode <2>: ASCII export. (line 6) * transient-mark-mode <3>: Built-in table editor. - (line 167) + (line 165) * transient-mark-mode: Structure editing. (line 46) * trees, sparse: Sparse trees. (line 6) * trees, visibility: Visibility cycling. (line 6) @@ -3672,12 +3666,12 @@ File: org, Node: Key Index, Prev: Index, Up: Top * <1>: Agenda commands. (line 41) * <2>: Creating timestamps. (line 100) * : Built-in table editor. - (line 66) + (line 64) * : Agenda commands. (line 81) * : Agenda commands. (line 28) * <1>: Agenda commands. (line 35) * <2>: Built-in table editor. - (line 59) + (line 57) * <3>: Plain Lists. (line 37) * : Visibility cycling. (line 10) * > <1>: Agenda commands. (line 140) @@ -3685,7 +3679,7 @@ File: org, Node: Key Index, Prev: Index, Up: Top * C: Agenda commands. (line 170) * c: Agenda commands. (line 154) * C-#: Built-in table editor. - (line 157) + (line 155) * C-,: Agenda files. (line 18) * C-c !: Creating timestamps. (line 21) * C-c $: Archiving. (line 9) @@ -3694,35 +3688,35 @@ File: org, Node: Key Index, Prev: Index, Up: Top * C-c ' <1>: Editing/debugging formulas. (line 20) * C-c ': Built-in table editor. - (line 146) + (line 144) * C-c *: Built-in table editor. - (line 150) + (line 148) * C-c +: Built-in table editor. - (line 167) + (line 165) * C-c ,: Priorities. (line 18) * C-c -: Built-in table editor. - (line 94) + (line 92) * C-c .: Creating timestamps. (line 10) * C-c /: Sparse trees. (line 15) * C-c :: HTML export. (line 17) * C-c ;: Comment lines. (line 12) * C-c <: Creating timestamps. (line 25) * C-c : Built-in table editor. - (line 189) + (line 187) * C-c =: Built-in table editor. - (line 137) + (line 135) * C-c >: Creating timestamps. (line 29) * C-c ? <1>: Editing/debugging formulas. (line 20) * C-c ?: Built-in table editor. - (line 163) + (line 161) * C-c [: Agenda files. (line 12) * C-c \: Tag searches. (line 9) * C-c ]: Agenda files. (line 15) * C-c ^: Built-in table editor. - (line 98) + (line 96) * C-c `: Built-in table editor. - (line 183) + (line 181) * C-c a a: Weekly/Daily Agenda. (line 9) * C-c a C: Agenda dispatcher. (line 30) * C-c a M: Matching headline tags. @@ -3741,7 +3735,7 @@ File: org, Node: Key Index, Prev: Index, Up: Top * C-c C-c <3>: Editing/debugging formulas. (line 16) * C-c C-c <4>: Built-in table editor. - (line 44) + (line 54) * C-c C-c: Plain Lists. (line 61) * C-c C-d: Creating timestamps. (line 37) * C-c C-f: Motion. (line 12) @@ -3754,7 +3748,7 @@ File: org, Node: Key Index, Prev: Index, Up: Top * C-c C-q <1>: Editing/debugging formulas. (line 20) * C-c C-q: Built-in table editor. - (line 121) + (line 119) * C-c C-r: Timeline. (line 13) * C-c C-s: Creating timestamps. (line 47) * C-c C-t: TODO basics. (line 13) @@ -3768,26 +3762,26 @@ File: org, Node: Key Index, Prev: Index, Up: Top * C-c C-x C-i: iCalendar export. (line 15) * C-c C-x C-k: Structure editing. (line 31) * C-c C-x C-w <1>: Built-in table editor. - (line 110) + (line 108) * C-c C-x C-w: Structure editing. (line 31) * C-c C-x C-y <1>: Built-in table editor. - (line 114) + (line 112) * C-c C-x C-y: Structure editing. (line 38) * C-c C-x h: HTML export. (line 10) * C-c C-x i: iCalendar export. (line 13) * C-c C-x M-w <1>: Built-in table editor. - (line 107) + (line 105) * C-c C-x M-w: Structure editing. (line 35) * C-c C-x t: HTML export. (line 14) * C-c C-x v: Sparse trees. (line 39) * C-c C-y: Creating timestamps. (line 63) * C-c l: Managing links. (line 9) * C-c |: Built-in table editor. - (line 193) + (line 40) * C-c ~: table.el. (line 18) * C-u C-c .: Creating timestamps. (line 16) * C-u C-c =: Built-in table editor. - (line 141) + (line 139) * C-u C-c C-l: Managing links. (line 36) * D: Agenda commands. (line 66) * d: Agenda commands. (line 63) @@ -3799,37 +3793,37 @@ File: org, Node: Key Index, Prev: Index, Up: Top * L: Agenda commands. (line 32) * M: Agenda commands. (line 161) * M-: Built-in table editor. - (line 84) + (line 82) * M- <1>: Built-in table editor. - (line 74) + (line 72) * M-: Structure editing. (line 13) * M- <1>: Plain Lists. (line 42) * M-: Structure editing. (line 6) * M- <1>: Built-in table editor. - (line 74) + (line 72) * M-: Structure editing. (line 16) * M- <1>: Completion. (line 10) * M- <2>: Setting tags. (line 6) * M-: Per file keywords. (line 17) * M-: Built-in table editor. - (line 84) + (line 82) * M-S- <1>: Built-in table editor. - (line 91) + (line 89) * M-S- <2>: Plain Lists. (line 46) * M-S-: Structure editing. (line 28) * M-S- <1>: Creating timestamps. (line 97) * M-S- <2>: Built-in table editor. - (line 78) + (line 76) * M-S- <3>: Plain Lists. (line 52) * M-S-: Structure editing. (line 19) * M-S-: Structure editing. (line 10) * M-S- <1>: Creating timestamps. (line 94) * M-S- <2>: Built-in table editor. - (line 81) + (line 79) * M-S- <3>: Plain Lists. (line 52) * M-S-: Structure editing. (line 22) * M-S- <1>: Built-in table editor. - (line 88) + (line 86) * M-S- <2>: Plain Lists. (line 46) * M-S-: Structure editing. (line 25) * mouse-1 <1>: Agenda commands. (line 35) @@ -3853,11 +3847,11 @@ File: org, Node: Key Index, Prev: Index, Up: Top * S- <1>: Agenda commands. (line 136) * S-: Creating timestamps. (line 50) * S-: Built-in table editor. - (line 172) + (line 170) * S- <1>: Agenda commands. (line 128) * S-: Creating timestamps. (line 50) * S- <1>: Built-in table editor. - (line 63) + (line 61) * S-: Visibility cycling. (line 19) * S- <1>: Agenda commands. (line 118) * S- <2>: Creating timestamps. (line 55) @@ -3870,97 +3864,96 @@ File: org, Node: Key Index, Prev: Index, Up: Top  Tag Table: -Node: Top960 -Node: Introduction7181 -Node: Summary7495 -Node: Installation and activation9607 -Node: Feedback11612 -Node: Document Structure12398 -Node: Outlines13164 -Node: Headlines13824 -Node: Visibility cycling14447 -Node: Motion15638 -Node: Structure editing16422 -Node: Archiving18165 -Node: Sparse trees19025 -Ref: Sparse trees-Footnote-121054 -Ref: Sparse trees-Footnote-221146 -Node: Plain Lists21260 -Ref: Plain Lists-Footnote-124016 -Node: Tables24373 -Node: Built-in table editor24921 -Node: Narrow columns32811 -Ref: Narrow columns-Footnote-134744 -Node: Table calculations34790 -Node: Formula syntax35966 -Ref: Formula syntax-Footnote-138900 -Node: Column formulas39199 -Node: Advanced features40961 -Node: Named-field formulas44216 -Node: Editing/debugging formulas44856 -Node: Appetizer46614 -Node: orgtbl-mode47716 -Node: table.el48207 -Node: Hyperlinks49184 -Node: Link format49818 -Node: Internal links51000 -Node: Radio targets52890 -Node: CamelCase links53605 -Node: External links54204 -Ref: External links-Footnote-156129 -Node: Managing links56268 -Node: Search Options60246 -Ref: Search Options-Footnote-161566 -Node: Remember61647 -Ref: Remember-Footnote-165528 -Node: TODO items65652 -Node: TODO basics66575 -Node: Progress logging68090 -Node: TODO extensions68876 -Node: Workflow states69676 -Node: TODO types70544 -Ref: TODO types-Footnote-172202 -Node: Per file keywords72284 -Ref: Per file keywords-Footnote-173737 -Node: Priorities73965 -Node: Timestamps75174 -Node: Time stamps75495 -Node: Creating timestamps77510 -Node: Tags80639 -Node: Tag inheritance81374 -Node: Setting tags82311 -Node: Tag searches83273 -Node: Agenda Views84482 -Node: Agenda files86021 -Ref: Agenda files-Footnote-186981 -Ref: Agenda files-Footnote-287130 -Node: Agenda dispatcher87322 -Node: Weekly/Daily Agenda89452 -Node: Categories90587 -Node: Time-of-day specifications91235 -Node: Calendar/Diary integration93211 -Node: Sorting of agenda items94588 -Node: Global TODO list95420 -Node: Matching headline tags96835 -Node: Timeline97778 -Node: Agenda commands98651 -Node: Exporting103906 -Node: ASCII export104478 -Node: HTML export105313 -Node: HTML formatting106429 -Node: Export options108061 -Node: Comment lines110252 -Node: iCalendar export110722 -Node: Miscellaneous112517 -Node: Completion113144 -Node: Customization114140 -Node: Clean view114588 -Node: TTY keys117228 -Node: FAQ118829 -Node: Interaction124335 -Node: Bugs127176 -Node: Acknowledgments129485 -Node: Index132415 -Node: Key Index152984 +Node: Top959 +Node: Introduction7179 +Node: Summary7493 +Node: Installation and activation9605 +Node: Feedback11274 +Node: Document Structure12060 +Node: Outlines12826 +Node: Headlines13486 +Node: Visibility cycling14109 +Node: Motion15300 +Node: Structure editing16084 +Node: Archiving17827 +Node: Sparse trees18687 +Ref: Sparse trees-Footnote-120716 +Ref: Sparse trees-Footnote-220808 +Node: Plain Lists20922 +Ref: Plain Lists-Footnote-123678 +Node: Tables24035 +Node: Built-in table editor24583 +Node: Narrow columns32197 +Ref: Narrow columns-Footnote-134130 +Node: Table calculations34176 +Node: Formula syntax35352 +Ref: Formula syntax-Footnote-138286 +Node: Column formulas38585 +Node: Advanced features40347 +Node: Named-field formulas43602 +Node: Editing/debugging formulas44242 +Node: Appetizer46000 +Node: orgtbl-mode47102 +Node: table.el47593 +Node: Hyperlinks48570 +Node: Link format49204 +Node: Internal links50500 +Node: Radio targets52390 +Node: CamelCase links53105 +Node: External links53603 +Node: Managing links55528 +Node: Search Options59512 +Ref: Search Options-Footnote-160832 +Node: Remember60913 +Ref: Remember-Footnote-164779 +Node: TODO items64903 +Node: TODO basics65826 +Node: Progress logging67341 +Node: TODO extensions68127 +Node: Workflow states68927 +Node: TODO types69795 +Ref: TODO types-Footnote-171453 +Node: Per file keywords71535 +Ref: Per file keywords-Footnote-172988 +Node: Priorities73216 +Node: Timestamps74425 +Node: Time stamps74746 +Node: Creating timestamps76761 +Node: Tags79890 +Node: Tag inheritance80625 +Node: Setting tags81562 +Node: Tag searches82524 +Node: Agenda Views83733 +Node: Agenda files85272 +Ref: Agenda files-Footnote-186232 +Ref: Agenda files-Footnote-286381 +Node: Agenda dispatcher86573 +Node: Weekly/Daily Agenda88703 +Node: Categories89838 +Node: Time-of-day specifications90486 +Node: Calendar/Diary integration92462 +Node: Sorting of agenda items93839 +Node: Global TODO list94671 +Node: Matching headline tags96086 +Node: Timeline97029 +Node: Agenda commands97902 +Node: Exporting103158 +Node: ASCII export103730 +Node: HTML export104565 +Node: HTML formatting105681 +Node: Export options107313 +Node: Comment lines109504 +Node: iCalendar export109974 +Node: Miscellaneous111769 +Node: Completion112396 +Node: Customization113392 +Node: Clean view113840 +Node: TTY keys116480 +Node: FAQ118081 +Node: Interaction124316 +Node: Bugs127157 +Node: Acknowledgments129466 +Node: Index132396 +Node: Key Index153038  End Tag Table diff --git a/org.el b/org.el index cbddaf280..d58d85112 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.19b +;; Version: 4.20 ;; ;; This file is part of GNU Emacs. ;; @@ -87,6 +87,8 @@ ;; - If a link has a description, only the description is displayed ;; the link part is hidden. Use C-c C-l to edit the link part. ;; - TAGS are now bold, but in the same color as the headline. +;; - The width of a table column can be limited by using a field "". +;; - New structure for the customization tree. ;; - Bug fixes. ;; ;; Version 4.13 @@ -169,7 +171,7 @@ ;;; Customization variables -(defvar org-version "4.19b" +(defvar org-version "4.20" "The version number of the file org.el.") (defun org-version () (interactive) @@ -400,7 +402,6 @@ body starts at column 0, indentation is not changed at all." :group 'org-edit-structure :type 'boolean) -;; FIXME: in the wrong group, but where would it fit???? (defcustom org-enable-fixed-width-editor t "Non-nil means, lines starting with \":\" are treated as fixed-width. This currently only means, they are never auto-wrapped. @@ -593,17 +594,6 @@ this variable requires a restart of Emacs to become effective." :group 'org-table-settings :type 'string) -(defcustom org-table-spaces-around-separators '(1 . 1) - "The number of spaces to be placed before and after separators." - :group 'org-table-settings - :type '(cons (number :tag "Before \"|\"") (number :tag " After \"|\""))) - -(defcustom org-table-spaces-around-invisible-separators '(1 . 2) - "The number of spaces to be placed before and after separators. -This option applies when the column separators have been made invisible." - :group 'org-table-settings - :type '(cons (number :tag "Before \"|\"") (number :tag " After \"|\""))) - (defcustom org-table-number-regexp "^[<>]?[-+^.0-9]*[0-9][-+^.0-9eEdDx()%]*$" "Regular expression for recognizing numbers in table columns. If a table column contains mostly numbers, it will be aligned to the @@ -652,7 +642,7 @@ removal/insertion." :group 'org-table-editing :type 'boolean) -(defcustom org-table-limit-column-width t +(defcustom org-table-limit-column-width t ;kw "Non-nil means, allow to limit the width of table columns with fields." :group 'org-table-editing :type 'boolean) @@ -792,33 +782,30 @@ additional URL: prefix, so the format would be \"\"." (const :tag "\"\" (e.g. )" "") (string :tag "Other" :value "<%s>"))) -(defvaralias 'org-allow-space-in-links 'org-allow-space-in-plain-links) +(defcustom org-activate-links '(bracket angle plain radio tag date) + "Types of links that should be activated in Org-mode files. +This is a list of symbols, each leading to the activation of a certain link +type. In principle, it does not hurt to turn on most link types - there may +be a small gain when turning off unused link types. The types are: -(defcustom org-allow-space-in-plain-links nil - "Non-nil means, space characters may be part of a plain text link. -Space characters are no problem in links enclosed by double square brackets. -But in plain text, if space is allowed, org-mode does not know where to -terminate the link and reads until the end of the line. -This variable exists only to force compatibility with old org-mode files. -I discourage setting this to t, and support for this may not be available -in the future. -Changing this requires a restart of Emacs to become effective." - :group 'org-link - :type 'boolean) +bracket The recommended [[link][description]] or [[link]] links with hiding. +angular Links in angular brackes that may contain whitespace like + . +plain Plain links in normal text, no whitespace, like http://google.com. +radio Text that is matched by a radio target, see manual for details. +tag Tag settings in a headline (link to tag search). +date Time stamps (link to calendar). +camel CamelCase words defining text searches. -(defcustom org-radio-targets t - "Non-nil means activate text matching a link target. -Radio targets are strings in triple angular brackets, like <<>>. -When this option is set, any occurrence of \"my target\" in normal text -becomes a link." +Changing this variable requires a restart of Emacs to become effective." :group 'org-link - :type 'boolean) - -(defcustom org-activate-camels nil - "Non-nil means, treat words in CamelCase as in-file links. -Changing this requires restart of Emacs to become effective." - :group 'org-link - :type 'boolean) + :type '(set (const :tag "Double bracket links (new style)" bracket) + (const :tag "Angular bracket links (old style)" angular) + (const :tag "plain text links" plain) + (const :tag "Radio target matches" radio) + (const :tag "Tags" tag) + (const :tag "Timestamps" date) + (const :tag "CamelCase words" camel))) (defgroup org-link-store nil "Options concerning storing links in Org-mode" @@ -930,11 +917,22 @@ When nil, an error will be generated." :group 'org-link-follow :type 'boolean) -(defcustom org-confirm-shell-links t +(defcustom org-confirm-shell-links 'yes-or-no-p "Non-nil means, ask for confirmation before executing shell links. -The default is true, to keep new users from shooting into their own foot." +Shell links can be dangerous, just thing about a link + + [[shell:rm -rf ~/*][Google Search]] + +This link would show up in your Org-mode document as \"Google Search\" +but really it would remove your entire home directory. Dangerous indeed. +Therefore I *definitely* advise agains setting this varaiable to nil. +Just change it to `y-or-n-p' of you want to confirm with a single key press +rather than having to type \"yes\"." :group 'org-link-follow - :type 'boolean) + :type '(choice + (const :tag "with yes-or-no (safer)" yes-or-no-p) + (const :tag "with y-or-n (faster)" y-or-n-p) + (const :tag "no confirmation (dangerous)" nil))) (defconst org-file-apps-defaults-gnu '((t . mailcap)) @@ -1083,37 +1081,14 @@ Changes become only effective after restarting Emacs." (defcustom org-todo-interpretation 'sequence "Controls how TODO keywords are interpreted. -\\Possible values are `sequence' and `type'. This variable is only relevant if `org-todo-keywords' contains more than two -states. There are two ways how these keywords can be used: +states. \\Possible values are `sequence' and `type'. -- As a sequence in the process of working on a TODO item, for example - (setq org-todo-keywords '(\"TODO\" \"STARTED\" \"VERIFY\" \"DONE\") - org-todo-interpretation 'sequence) - -- As different types of TODO items, for example - (setq org-todo-keywords '(\"URGENT\" \"RELAXED\" \"REMIND\" \"FOR_TOM\" \"DONE\") - org-todo-interpretation 'type) - -When the states are interpreted as a sequence, \\[org-todo] always cycles -to the next state, in order to walk through all different states. So with -\\[org-todo], you turn an empty entry into the state TODO. When you started -working on the item, you use \\[org-todo] again to switch it to \"STARTED\", -later to VERIFY and finally to DONE. - -When the states are interpreted as types, \\[org-todo] still cycles through -when it is called several times in direct succession, in order to initially -select the type. However, if not called immediately after a previous -\\[org-todo], it switches from each type directly to DONE. So with the -above example, you could use `\\[org-todo] \\[org-todo]' to label an entry -RELAXED. If you later return to this entry and press \\[org-todo] again, -RELAXED will not be changed REMIND, but directly to DONE. - -You can create a large number of types. To initially select a -type, it is then best to use \\[universal-argument] \\[org-todo] in order to specify the -type with completion. Of course, you can also type the keyword -directly into the buffer. M-TAB completes TODO keywords at the -beginning of a headline." +When `sequence', \\[org-todo] will always switch to the next state in the +`org-todo-keywords' list. When `type', \\[org-todo] only cycles from state +to state when executed several times in direct succession. Otherwise, it +switches directly to DONE from any state. +See the manual for more information." :group 'org-todo :group 'org-keywords :type '(choice (const sequence) @@ -1133,7 +1108,6 @@ closing date." :group 'org-todo :type 'boolean) -;; FIXME: Correct to put this into the TODO group??? (defgroup org-priorities nil "Keywords in Org-mode." :tag "Org Priorities" @@ -1150,21 +1124,6 @@ This is the priority an item get if no explicit priority is given." :group 'org-priorities :type 'character) -;; FIXME: move to agenda????? -(defvar org-category nil - "Variable used by org files to set a category for agenda display. -Such files should use a file variable to set it, for example - - -*- mode: org; org-category: \"ELisp\" - -or contain a special line - -#+CATEGORY: ELisp - -If the file does not specify a category, then file's base name -is used instead.") -(make-variable-buffer-local 'org-category) - (defgroup org-time nil "Options concerning time stamps and deadlines in Org-mode." :tag "Org Time" @@ -1238,7 +1197,7 @@ companion option `org-tags-match-list-sublevels'." Because of tag inheritance (see variable `org-use-tag-inheritance'), the sublevels of a headline matching a tag search often also match the same search. Listing all of them can create very long lists. -Setting this variable to nil causes subtrees to be skipped. +Setting this variable to nil causes subtrees of a match to be skipped. This option is off by default, because inheritance in on. If you turn inheritance off, you very likely want to turn this option on. @@ -1258,14 +1217,28 @@ make sure all corresponding TODO items find their way into the list." :tag "Org Agenda" :group 'org) +(defvar org-category nil + "Variable used by org files to set a category for agenda display. +Such files should use a file variable to set it, for example + + -*- mode: org; org-category: \"ELisp\" + +or contain a special line + +#+CATEGORY: ELisp + +If the file does not specify a category, then file's base name +is used instead.") +(make-variable-buffer-local 'org-category) + (defcustom org-agenda-files nil "The files to be used for agenda display. Entries may be added to this list with \\[org-agenda-file-to-front] and removed with \\[org-remove-file]. You can also use customize to edit the list. If the value of the variable is not a list but a single file name, then -the list of agenda files is actually stored in that file, one agenda file -per line" +the list of agenda files is actually stored and maintained in that file, one +agenda file per line." :group 'org-agenda :type '(choice (repeat :tag "List of files" file) @@ -1355,7 +1328,7 @@ When nil, only the days which actually have entries are shown." (defcustom org-agenda-start-on-weekday 1 "Non-nil means, start the overview always on the specified weekday. -0 Denotes Sunday, 1 denotes Monday etc. +0 denotes Sunday, 1 denotes Monday etc. When nil, always start on the current day." :group 'org-agenda-display :type '(choice (const :tag "Today" nil) @@ -1521,6 +1494,7 @@ See also the variables `org-agenda-remove-times-when-in-prefix' and Depending on which command was used last, this may be the compiled version of `org-agenda-prefix-format' or `org-timeline-prefix-format'.") +;; FIXME: There seem to be situations where this does no work. (defcustom org-agenda-remove-times-when-in-prefix t "Non-nil means, remove duplicate time specifications in agenda items. When the format `org-agenda-prefix-format' contains a `%t' specifier, a @@ -1539,7 +1513,7 @@ the headline/diary entry." (const :tag "When at beginning of entry" beg))) (defcustom org-agenda-remove-tags-when-in-prefix nil - "Non-nil means, the tags from copy of headline in agenda. + "Non-nil means, remove the tags from the headline copy in the agenda. When this is the symbol `prefix', only remove tags when `org-agenda-prefix-format' contains a `%T' specifier." :group 'org-agenda-prefix @@ -1615,27 +1589,10 @@ This option can also be set with the +OPTIONS line, e.g. \"toc:nil\"." :group 'org-export-general :type 'boolean) -(defcustom org-export-plain-list-max-depth 20 - "Maximum depth of hand-formatted lists in HTML export. - -Org-mode parses hand-formatted enumeration and bullet lists and -transforms them to HTML open export. Different indentation of the -bullet or number indicates different list nesting levels. To avoid -confusion, only a single level is allowed by default. When this is -larger than 1, deeper indentation leads to deeper list nesting. For -example, the default value of 3 allows the following list to be -formatted correctly in HTML: - - * Fruit - - Apple - - Banana - 1. from Africa - 2. from South America - - Pineapple - * Bread - * Dairy products" +(defcustom org-export-mark-todo-in-toc nil + "Non-nil means, mark TOC lines that contain any open TODO items." :group 'org-export-general - :type 'integer) + :type 'boolean) (defcustom org-export-preserve-breaks nil "Non-nil means, preserve all line breaks when exporting. @@ -1646,6 +1603,11 @@ This option can also be set with the +OPTIONS line, e.g. \"\\n:t\"." :group 'org-export-general :type 'boolean) +(defgroup org-export-translation nil + "Options for translating special ascii sequences for the export backends." + :tag "Org Export Translation" + :group 'org-export) + (defcustom org-export-with-emphasize t "Non-nil means, interpret *word*, /word/, and _word_ as emphasized text. If the export target supports emphasizing text, the word will be @@ -1654,16 +1616,9 @@ single words, but you can say: I *really* *mean* *this*. Not all export backends support this. This option can also be set with the +OPTIONS line, e.g. \"*:nil\"." - :group 'org-export-general + :group 'org-export-translation :type 'boolean) -;; FIXME: Is this in the right place???? -(defcustom org-match-sexp-depth 3 - "Number of stacked braces for sub/superscript matching. -This has to be set before loading org.el to be effective." - :group 'org-export-general - :type 'integer) - (defcustom org-export-with-sub-superscripts t "Non-nil means, interpret \"_\" and \"^\" for export. When this option is turned on, you can use TeX-like syntax for sub- and @@ -1680,10 +1635,10 @@ sub- or superscripts. Still, ambiguity is possible - so when in doubt use {} to enclose the sub/superscript. -Not all export backends support this. +Not all export backends support this, but HTML does. This option can also be set with the +OPTIONS line, e.g. \"^:nil\"." - :group 'org-export-general + :group 'org-export-translation :type 'boolean) (defcustom org-export-with-TeX-macros t @@ -1695,7 +1650,7 @@ names in HTML export, see the constant `org-html-entities'. Not all export backends support this. This option can also be set with the +OPTIONS line, e.g. \"TeX:nil\"." - :group 'org-export-general + :group 'org-export-translation :type 'boolean) (defcustom org-export-with-fixed-width t @@ -1705,13 +1660,24 @@ example: : ;; Some Lisp examples : (while (defc cnt) : (ding)) -will be looking just like this in also HTML. +will be looking just like this in also HTML. See also the QUOTE keyword. Not all export backends support this. This option can also be set with the +OPTIONS line, e.g. \"::nil\"." - :group 'org-export-general + :group 'org-export-translation :type 'boolean) +(defcustom org-match-sexp-depth 3 + "Number of stacked braces for sub/superscript matching. +This has to be set before loading org.el to be effective." + :group 'org-export-translation + :type 'integer) + +(defgroup org-export-tables nil + "Options for exporting tables in Org-mode." + :tag "Org Export Tables" + :group 'org-export) + (defcustom org-export-with-tables t "If non-nil, lines starting with \"|\" define a table. For example: @@ -1723,7 +1689,7 @@ For example: Not all export backends support this. This option can also be set with the +OPTIONS line, e.g. \"|:nil\"." - :group 'org-export-general + :group 'org-export-tables :type 'boolean) (defcustom org-export-highlight-first-table-line t @@ -1732,7 +1698,7 @@ In HTML export, this means use instead of . In tables created with table.el, this applies to the first table line. In Org-mode tables, all lines before the first horizontal separator line will be formatted with tags." - :group 'org-export-general + :group 'org-export-tables :type 'boolean) (defcustom org-export-table-remove-special-lines t @@ -1741,7 +1707,7 @@ This removes the special marking character column from tables that are set up for spreadsheet calculations. It also removes the entire lines marked with `!', `_', or `^'. The lines with `$' are kept, because the values of constants may be useful to have." - :group 'org-export-general + :group 'org-export-tables :type 'boolean) (defcustom org-export-prefer-native-exporter-for-tables nil @@ -1752,7 +1718,7 @@ the table does not use row- or column-spanning). This has the advantage, that the automatic HTML conversions for math symbols and sub/superscripts can be applied. Org-mode's HTML generator is also much faster." - :group 'org-export-general + :group 'org-export-tables :type 'boolean) (defgroup org-export-ascii nil @@ -1771,7 +1737,7 @@ Otherwise the buffer will just be saved to a file and stay hidden." :tag "Org Export XML" :group 'org-export) -(defcustom org-export-xml-type 'xoxo +(defcustom org-export-xml-type 'xoxo ;kw, if we have only one. "The kind of XML to be produced by the XML exporter. Allowed values are: xoxo The XOXO exporter." @@ -2341,8 +2307,8 @@ The following commands are available: (easy-menu-add org-org-menu) (easy-menu-add org-tbl-menu) (org-install-agenda-files-menu) - (if org-descriptive-links (org-add-to-invisibility-spec '(org-link . nil))) - (org-add-to-invisibility-spec '(org-cwidth . nil)) + (if org-descriptive-links (org-add-to-invisibility-spec '(org-link))) + (org-add-to-invisibility-spec '(org-cwidth)) (setq outline-regexp "\\*+") ;;(setq outline-regexp "\\(?:\\*+\\|[ \t]*\\(?:[-+*]\\|[0-9]+[.)]\\) \\)") (setq outline-level 'org-outline-level) @@ -2399,9 +2365,15 @@ The following commands are available: (defsubst org-current-line (&optional pos) (+ (if (bolp) 1 0) (count-lines (point-min) (or pos (point))))) +(defconst org-rm-props '(invisible t face t keymap t intangible t mouse-face t + mouse-map t) + "Properties to remove when a string without properties is wanted.") + (defsubst org-match-string-no-properties (num &optional string) (if (featurep 'xemacs) - (match-string num string) + (let ((s (match-string num string))) + (remove-text-properties 0 (length s) org-rm-props s) + s) (match-string-no-properties num string))) (defun org-current-time () @@ -2414,11 +2386,15 @@ The following commands are available: (nthcdr 2 time)))) (current-time))) -;; FIXME: `propertize' does copy the string first... -(defun org-string-props (string &rest properties) - "Add PROPERTIES to string." - (add-text-properties 0 (length string) properties string) +(defun org-add-props (string plist &rest props) + "Add text properties to entire string, from beginning to end. +PLIST may be a list of properties, PROPS are individual properties and values +that will be added to PLIST. Returns the string that was modified." + (add-text-properties + 0 (length string) (if props (append plist props) plist) string) string) +(put 'org-add-props 'lisp-indent-function 2) + ;;; Font-Lock stuff @@ -2437,7 +2413,7 @@ The following commands are available: (require 'font-lock) -(defconst org-non-link-chars "]\t\n\r|<>\000") +(defconst org-non-link-chars "]\t\n\r<>") (defconst org-link-types '("https?" "ftp" "mailto" "file" "news" "bbdb" "vm" "wl" "mhe" "rmail" "gnus" "shell")) (defconst org-link-re-with-space @@ -2445,19 +2421,29 @@ The following commands are available: "?")) -(defconst org-link-re-no-space + "[^" org-non-link-chars " ]\\)>?") + "Matches a link with spaces, optional angular brackets around it.") + +(defconst org-link-re-with-space2 (concat "?")) -(defconst org-link-regexp - (if org-allow-space-in-plain-links - org-link-re-with-space - org-link-re-no-space) - "Regular expression for matching links in plain text.") -(defconst org-external-link-maybe-brackets - (concat "\\(\\[\\[\\)?\\(" org-link-regexp "\\)\\(\\]\\(\\]\\|\\[\\)\\)?") - "Matches a link and optionally surrounding brackets.") + "\\([^" org-non-link-chars " ]" + "[^]\t\n\r]*" + "[^" org-non-link-chars " ]\\)>?") + "Matches a link with spaces, optional angular brackets around it.") + +(defconst org-angle-link-re + (concat + "<\\(" (mapconcat 'identity org-link-types "\\|") "\\):" + "\\([^" org-non-link-chars " ]" + "[^" org-non-link-chars "]*" + "\\)>") + "Matches link with angular brackets, spaces are allowed.") +(defconst org-plain-link-re + (concat + "\\(" (mapconcat 'identity org-link-types "\\|") "\\):" + "\\([^]\t\n\r<>,;() ]+\\)") + "Matches plain link, without spaces.") (defconst org-bracket-link-regexp "\\[\\[\\([^]]+\\)\\]\\(\\[\\([^]]+\\)\\]\\)?\\]" @@ -2496,9 +2482,9 @@ The following commands are available: org-ts-regexp "\\)?") "Regular expression matching a time stamp or time stamp range.") -(defun org-activate-links (limit) +(defun org-activate-plain-links (limit) "Run through the buffer and add overlays to links." - (if (re-search-forward org-link-regexp limit t) + (if (re-search-forward org-plain-link-re limit t) (progn (add-text-properties (match-beginning 0) (match-end 0) (list 'mouse-face 'highlight @@ -2506,7 +2492,17 @@ The following commands are available: )) t))) -(defun org-activate-links2 (limit) +(defun org-activate-angle-links (limit) + "Run through the buffer and add overlays to links." + (if (re-search-forward org-angle-link-re limit t) + (progn + (add-text-properties (match-beginning 0) (match-end 0) + (list 'mouse-face 'highlight + 'keymap org-mouse-map + )) + t))) + +(defun org-activate-bracket-links (limit) "Run through the buffer and add overlays to bracketed links." (if (re-search-forward org-bracket-link-regexp limit t) (let* ((help (concat "LINK: " (org-match-string-no-properties 1))) @@ -2548,7 +2544,7 @@ The following commands are available: (defun org-activate-target-links (limit) "Run through the buffer and add overlays to target matches." - (when (and org-radio-targets org-target-link-regexp) + (when org-target-link-regexp (let ((case-fold-search t)) (if (re-search-forward org-target-link-regexp limit t) (progn @@ -2562,21 +2558,20 @@ The following commands are available: (defun org-update-radio-target-regexp () "Find all radio targets in this file and update the regular expression." (interactive) - (when org-radio-targets + (when (memq 'radio org-activate-links) (setq org-target-link-regexp (org-make-target-link-regexp (org-all-targets 'radio))) (org-restart-font-lock))) (defun org-hide-wide-columns (limit) - (when org-table-limit-column-width - (let (s e) - (setq s (text-property-any (point) (or limit (point-max)) - 'org-cwidth t)) - (when s - (setq e (next-single-property-change s 'org-cwidth)) - (add-text-properties s e '(invisible org-cwidth intangible t)) - (goto-char e) - t)))) + (let (s e) + (setq s (text-property-any (point) (or limit (point-max)) + 'org-cwidth t)) + (when s + (setq e (next-single-property-change s 'org-cwidth)) + (add-text-properties s e '(invisible org-cwidth intangible t)) + (goto-char e) + t))) (defun org-restart-font-lock () "Restart font-lock-mode, to force refontification." @@ -2616,13 +2611,12 @@ between words." (defun org-activate-camels (limit) "Run through the buffer and add overlays to dates." - (if org-activate-camels - (if (re-search-forward org-camel-regexp limit t) - (progn - (add-text-properties (match-beginning 0) (match-end 0) - (list 'mouse-face 'highlight - 'keymap org-mouse-map)) - t)))) + (if (re-search-forward org-camel-regexp limit t) + (progn + (add-text-properties (match-beginning 0) (match-end 0) + (list 'mouse-face 'highlight + 'keymap org-mouse-map)) + t))) (defun org-activate-tags (limit) (if (re-search-forward "[ \t]\\(:[A-Za-z_@0-9:]+:\\)[ \r\n]" limit t) @@ -2648,19 +2642,22 @@ between words." (defun org-set-font-lock-defaults () (let* ((em org-fontify-emphasized-text) + (lk org-activate-links) (org-font-lock-extra-keywords (list '("^\\(\\**\\)\\(\\*\\)\\(.*\\)" (1 (org-get-level-face 1)) (2 (org-get-level-face 2)) (3 (org-get-level-face 3))) '("^[ \t]*\\(\\(|\\|\\+-[-+]\\).*\\S-\\)" (1 'org-table)) - '(org-activate-links (0 'org-link t)) - '(org-activate-links2 (0 'org-link t)) - '(org-activate-target-links (0 'org-link t)) - '(org-activate-dates (0 'org-link t)) - '(org-activate-camels (0 'org-link t)) - '(org-activate-tags (1 'org-tag prepend)) - '(org-hide-wide-columns (0 nil append)) + (if (memq 'angle lk) '(org-activate-angle-links (0 'org-link t))) + (if (memq 'plain lk) '(org-activate-plain-links (0 'org-link t))) + (if (memq 'bracket lk) '(org-activate-bracket-links (0 'org-link t))) + (if (memq 'radio lk) '(org-activate-target-links (0 'org-link t))) + (if (memq 'date lk) '(org-activate-dates (0 'org-link t))) + (if (memq 'camel lk) '(org-activate-camels (0 'org-link t))) + (if (memq 'tag lk) '(org-activate-tags (1 'org-tag prepend))) + (if org-table-limit-column-width + '(org-hide-wide-columns (0 nil append))) (list (concat "^\\*+[ \t]*" org-not-done-regexp) '(1 'org-warning t)) (list (concat "\\[#[A-Z]\\]") '(0 'org-special-keyword t)) @@ -4876,7 +4873,7 @@ C Configure your own agenda commands") ((eq type 'todo-tree) "TODO kwd tree") ((eq type 'occur-tree) "Occur tree") (t "???")) - (org-string-props string 'face 'org-link)))) + (org-add-props string nil 'face 'org-warning)))) (goto-char (point-min)) (if (fboundp 'fit-window-to-buffer) (fit-window-to-buffer)) (message "Press key for agenda command%s" @@ -5107,7 +5104,7 @@ dates." (calendar-month-name (extract-calendar-month date)) " " (number-to-string (extract-calendar-year date)) "\n") (put-text-property s (1- (point)) 'face - 'org-link) + 'org-level-3) (if (equal d today) (put-text-property s (1- (point)) 'org-today t)) (insert (org-finalize-agenda-entries rtn) "\n") @@ -5192,7 +5189,7 @@ NDAYS defaults to `org-agenda-ndays'." (when rtnall (insert "ALL CURRENTLY OPEN TODO ITEMS:\n") (add-text-properties (point-min) (1- (point)) - (list 'face 'org-link)) + (list 'face 'org-level-3)) (insert (org-finalize-agenda-entries rtnall) "\n"))) (while (setq d (pop day-numbers)) (setq date (calendar-gregorian-from-absolute d) @@ -5228,7 +5225,7 @@ NDAYS defaults to `org-agenda-ndays'." (calendar-month-name (extract-calendar-month date)) (extract-calendar-year date))) (put-text-property s (1- (point)) 'face - 'org-link) + 'org-level-3) (if rtnall (insert (org-finalize-agenda-entries (org-agenda-add-time-grid-maybe @@ -5299,7 +5296,7 @@ for a keyword. A numeric prefix directly selects the Nth keyword in (setq rtnall (append rtnall rtn)))) (insert "Global list of TODO items of type: ") (add-text-properties (point-min) (1- (point)) - (list 'face 'org-link)) + (list 'face 'org-level-3)) (setq pos (point)) (insert (or org-select-this-todo-keyword "ALL") "\n") (add-text-properties pos (1- (point)) (list 'face 'org-warning)) @@ -5311,7 +5308,7 @@ for a keyword. A numeric prefix directly selects the Nth keyword in (format "(%d)%s" (setq n (1+ n)) x)) org-todo-keywords " ")) "\n") - (add-text-properties pos (1- (point)) (list 'face 'org-link)) + (add-text-properties pos (1- (point)) (list 'face 'org-level-3)) (when rtnall (insert (org-finalize-agenda-entries rtnall) "\n")) (goto-char (point-min)) @@ -5545,11 +5542,7 @@ With prefix ARG, go back that many times `org-agenda-ndays'." (lambda (x) (setq x (org-format-agenda-item "" x "Diary" nil 'time)) ;; Extend the text properties to the beginning of the line - (add-text-properties - 0 (length x) - (text-properties-at (1- (length x)) x) - x) - x) + (org-add-props x (text-properties-at (1- (length x)) x))) entries))))) (defun org-agenda-cleanup-fancy-diary () @@ -5588,18 +5581,13 @@ date. It also removes lines that contain only whitespace." (defun org-modify-diary-entry-string (string) "Add text properties to string, allowing org-mode to act on it." - (add-text-properties - 0 (length string) - (list 'mouse-face 'highlight - 'keymap org-agenda-keymap - 'help-echo - (format - "mouse-2 or RET jump to diary file %s" - (abbreviate-file-name buffer-file-name)) - 'org-agenda-diary-link t - 'org-marker (org-agenda-new-marker (point-at-bol))) - string) - string) + (org-add-props string nil + 'mouse-face 'highlight + 'keymap org-agenda-keymap + 'help-echo (format "mouse-2 or RET jump to diary file %s" + (abbreviate-file-name buffer-file-name)) + 'org-agenda-diary-link t + 'org-marker (org-agenda-new-marker (point-at-bol)))) (defun org-diary-default-entry () "Add a dummy entry to the diary. @@ -5906,11 +5894,9 @@ the documentation of `org-diary'." (length (member (match-string 2) org-todo-keywords))) 1))) - (add-text-properties - 0 (length txt) (append (list 'org-marker marker 'org-hd-marker marker - 'priority priority 'category category) - props) - txt) + (org-add-props txt props + 'org-marker marker 'org-hd-marker marker + 'priority priority 'category category) (push txt ee) (goto-char (match-end 1))) (nreverse ee))) @@ -5966,32 +5952,19 @@ the documentation of `org-diary'." (match-string 1) category tags timestr))) (setq txt org-agenda-no-heading-message)) (setq priority (org-get-priority txt)) - (add-text-properties - 0 (length txt) (append (list 'org-marker marker - 'org-hd-marker hdmarker) props) - txt) + (org-add-props txt props + 'org-marker marker 'org-hd-marker hdmarker) (if deadlinep - (add-text-properties - 0 (length txt) - (list 'face - (if donep 'org-done 'org-warning) - 'undone-face 'org-warning - 'done-face 'org-done - 'category category - 'priority (+ 100 priority)) - txt) + (org-add-props txt nil + 'face (if donep 'org-done 'org-warning) + 'undone-face 'org-warning 'done-face 'org-done + 'category category 'priority (+ 100 priority)) (if scheduledp - (add-text-properties - 0 (length txt) - (list 'face 'org-scheduled-today - 'undone-face 'org-scheduled-today - 'done-face 'org-done - 'category category - priority (+ 99 priority)) - txt) - (add-text-properties - 0 (length txt) - (list 'priority priority 'category category) txt))) + (org-add-props txt nil + 'face 'org-scheduled-today + 'undone-face 'org-scheduled-today 'done-face 'org-done + 'category category priority (+ 99 priority)) + (org-add-props txt nil 'priority priority 'category category))) (push txt ee)) (outline-next-heading)))) (nreverse ee))) @@ -6038,15 +6011,10 @@ the documentation of `org-diary'." (match-string 1) category tags timestr))) (setq txt org-agenda-no-heading-message)) (setq priority 100000) - (add-text-properties - 0 (length txt) (append (list 'org-marker marker - 'org-hd-marker hdmarker - 'face 'org-done - 'priority priority - 'category category - 'undone-face 'org-warning - 'done-face 'org-done) props) - txt) + (org-add-props txt props + 'org-marker marker 'org-hd-marker hdmarker 'face 'org-done + 'priority priority 'category category + 'undone-face 'org-warning 'done-face 'org-done) (push txt ee)) (outline-next-heading)))) (nreverse ee))) @@ -6091,23 +6059,19 @@ the documentation of `org-diary'." (format "In %3d d.: " diff) head category tags)))) (setq txt org-agenda-no-heading-message)) (when txt - (add-text-properties - 0 (length txt) - (append - (list 'org-marker (org-agenda-new-marker pos) - 'org-hd-marker (org-agenda-new-marker pos1) - 'priority (+ (- 10 diff) (org-get-priority txt)) - 'category category - 'face (cond ((<= diff 0) 'org-warning) - ((<= diff 5) 'org-scheduled-previously) - (t nil)) - 'undone-face (cond - ((<= diff 0) 'org-warning) - ((<= diff 5) 'org-scheduled-previously) - (t nil)) - 'done-face 'org-done) - props) - txt) + (org-add-props txt props + 'org-marker (org-agenda-new-marker pos) + 'org-hd-marker (org-agenda-new-marker pos1) + 'priority (+ (- 10 diff) (org-get-priority txt)) + 'category category + 'face (cond ((<= diff 0) 'org-warning) + ((<= diff 5) 'org-scheduled-previously) + (t nil)) + 'undone-face (cond + ((<= diff 0) 'org-warning) + ((<= diff 5) 'org-scheduled-previously) + (t nil)) + 'done-face 'org-done) (push txt ee))))) ee)) @@ -6152,13 +6116,11 @@ the documentation of `org-diary'." category tags)))) (setq txt org-agenda-no-heading-message)) (when txt - (add-text-properties - 0 (length txt) - (append (list 'org-marker (org-agenda-new-marker pos) - 'org-hd-marker (org-agenda-new-marker pos1) - 'priority (+ (- 5 diff) (org-get-priority txt)) - 'category category) - props) txt) + (org-add-props txt props + 'org-marker (org-agenda-new-marker pos) + 'org-hd-marker (org-agenda-new-marker pos1) + 'priority (+ (- 5 diff) (org-get-priority txt)) + 'category category) (push txt ee))))) ee)) @@ -6198,13 +6160,9 @@ the documentation of `org-diary'." (match-string 1) category tags (if (= d0 d1) timestr)))) (setq txt org-agenda-no-heading-message)) - (add-text-properties - 0 (length txt) (append (list 'org-marker marker - 'org-hd-marker hdmarker - 'priority (org-get-priority txt) - 'category category) - props) - txt) + (org-add-props txt props + 'org-marker marker 'org-hd-marker hdmarker + 'priority (org-get-priority txt) 'category category) (push txt ee))) (outline-next-heading)) ;; Sort the entries by expiration date. @@ -6311,14 +6269,11 @@ only the correctly processes TXT should be returned - this is used by (setq rtn (concat (eval org-prefix-format-compiled) txt))) ;; And finally add the text properties - (add-text-properties - 0 (length rtn) (list 'category (downcase category) - 'tags tags - 'prefix-length (- (length rtn) (length txt)) - 'time-of-day time-of-day - 'dotime dotime) - rtn) - rtn))) + (org-add-props rtn nil + 'category (downcase category) 'tags tags + 'prefix-length (- (length rtn) (length txt)) + 'time-of-day time-of-day + 'dotime dotime)))) (defun org-agenda-add-time-grid-maybe (list ndays todayp) (catch 'exit @@ -6940,12 +6895,8 @@ are included in the output." category tags-list)) (goto-char lspos) (setq marker (org-agenda-new-marker)) - (add-text-properties - 0 (length txt) - (append (list 'org-marker marker 'org-hd-marker marker - 'category category) - props) - txt) + (org-add-props txt props + 'org-marker marker 'org-hd-marker marker 'category category) (push txt rtn)) ;; if we are to skip sublevels, jump to end of subtree (point) @@ -7047,13 +6998,13 @@ The prefix arg TODO-ONLY limits the search to TODO entries." (setq rtnall (append rtnall rtn)))))))) (insert "Headlines with TAGS match: ") (add-text-properties (point-min) (1- (point)) - (list 'face 'org-link)) + (list 'face 'org-level-3)) (setq pos (point)) (insert match "\n") (add-text-properties pos (1- (point)) (list 'face 'org-warning)) (setq pos (point)) (insert "Press `C-u r' to search again with new search string\n") - (add-text-properties pos (1- (point)) (list 'face 'org-link)) + (add-text-properties pos (1- (point)) (list 'face 'org-level-3)) (when rtnall (insert (mapconcat 'identity rtnall "\n"))) (goto-char (point-min)) @@ -7192,10 +7143,10 @@ optional argument IN-EMACS is non-nil, Emacs will visit the file." (looking-at org-bracket-link-regexp) (<= (match-beginning 0) pos) (>= (match-end 0) pos)) - (setq link (org-link-unescape (match-string 1))) + (setq link (org-link-unescape (org-match-string-no-properties 1))) (while (string-match " *\n *" link) (setq link (replace-match " " t t link))) - (if (string-match org-link-re-with-space link) + (if (string-match org-link-re-with-space2 link) (setq type (match-string 1 link) path (match-string 2 link)) (setq type "thisfile" @@ -7212,11 +7163,12 @@ optional argument IN-EMACS is non-nil, Emacs will visit the file." (throw 'match t)) (save-excursion - (skip-chars-backward - (concat "^[]" org-non-link-chars - (if org-allow-space-in-plain-links " " ""))) - (when (or (looking-at org-link-regexp) - (and (re-search-forward org-link-regexp (point-at-eol) t) + (skip-chars-backward (concat "^[]" org-non-link-chars " ")) + (if (equal (char-before) ?<) (backward-char 1)) + (when (or (looking-at org-angle-link-re) + (looking-at org-plain-link-re) + (and (or (re-search-forward org-angle-link-re (point-at-eol) t) + (re-search-forward org-plain-link-re (point-at-eol) t)) (<= (match-beginning 0) pos) (>= (match-end 0) pos))) (setq type (match-string 1) @@ -7232,7 +7184,7 @@ optional argument IN-EMACS is non-nil, Emacs will visit the file." (throw 'match t))) (save-excursion (skip-chars-backward "a-zA-Z_") - (when (and org-activate-camels + (when (and (memq 'camel org-activate-links) (looking-at org-camel-regexp)) (setq type "camel" path (match-string 0)) (if (equal (char-before) ?*) @@ -7323,7 +7275,10 @@ optional argument IN-EMACS is non-nil, Emacs will visit the file." (while (string-match "@}" cmd) (setq cmd (replace-match ">" t t cmd))) (if (or (not org-confirm-shell-links) - (yes-or-no-p (format "Execute \"%s\" in the shell? " cmd))) + (funcall org-confirm-shell-links + (format "Execute \"%s\" in shell? " + (org-add-props cmd nil + 'face 'org-warning)))) (shell-command cmd) (error "Abort")))) @@ -8026,12 +7981,20 @@ For file links, arg negates `org-context-in-file-links'." (defun org-make-link-string (link &optional description) "Make a link with brackets, consisting of LINK and DESCRIPTION." - (if (eq org-link-style 'bracket) - (concat description "\n" link) - (if (stringp description) - ;; Remove brackets from the description, they are fatal. - (while (string-match "\\[\\|\\]" description) - (setq description (replace-match "" t t description)))) + (if (eq org-link-style 'plain) + (if (equal description link) + link + (concat description "\n" link)) + (when (stringp description) + ;; Remove brackets from the description, they are fatal. + (while (string-match "\\[\\|\\]" description) + (setq description (replace-match "" t t description)))) + (when (equal (org-link-escape link) description) + ;; No description needed, it is identical + (setq description nil)) + (when (and (not description) + (not (equal link (org-link-escape link)))) + (setq description link)) (concat "[[" (org-link-escape link) "]" (if description (concat "[" description "]") "") "]"))) @@ -8136,7 +8099,9 @@ is in the current directory or below." ;; We do have a link at point, and we are going to edit it. (setq remove (list (match-beginning 0) (match-end 0))) (setq desc (if (match-end 3) (org-match-string-no-properties 3))) - (setq link (read-string "Link: " (org-match-string-no-properties 1)))) + (setq link (read-string "Link: " + (org-link-unescape + (org-match-string-no-properties 1))))) (complete-file ;; Completing read for file names. (setq file (read-file-name "File: ")) @@ -8153,7 +8118,7 @@ is in the current directory or below." (t (setq link (org-make-link "file:" file)))))) (t ;; Read link, with completion for stored links. - (setq link (completing-read + (setq link (org-completing-read "Link: " org-stored-links nil nil nil org-insert-link-history (or (car (car org-stored-links))))) @@ -8164,7 +8129,7 @@ is in the current directory or below." (setq link (if entry (nth 1 entry) link) desc (or desc (nth 2 entry))))) - (if (string-match org-link-regexp link) + (if (string-match org-plain-link-re link) ;; URL-like link, normalize the use of angular brackets. (setq link (org-make-link (org-remove-angle-brackets link)))) @@ -8183,6 +8148,12 @@ is in the current directory or below." (if remove (apply 'delete-region remove)) (insert (org-make-link-string link desc)))) +(defun org-completing-read (&rest args) + (let ((minibuffer-local-completion-map + (copy-keymap minibuffer-local-completion-map))) + (define-key minibuffer-local-completion-map " " 'self-insert-command) + (apply 'completing-read args))) + ;;; Hooks for remember.el (defvar org-finish-function nil) @@ -8423,6 +8394,15 @@ and table.el tables." (org-table-convert))) (t (call-interactively 'table-insert)))) +(defun org-table-create-or-convert-from-region (arg) + "Convert region to table, or create an empty table. +If there is an active region, convert it to a table. If there is no such +region, create an empty table." + (interactive "P") + (if (org-region-active-p) + (org-table-convert-region (region-beginning) (region-end) arg) + (org-table-create arg))) + (defun org-table-create (&optional size) "Query for a size and insert a table skeleton. SIZE is a string Columns x Rows like for example \"3x2\"." @@ -8455,12 +8435,13 @@ SIZE is a string Columns x Rows like for example \"3x2\"." (goto-char pos))) (org-table-align))) -(defun org-table-convert-region (beg0 end0 nspace) +(defun org-table-convert-region (beg0 end0 &optional nspace) "Convert region to a table. The region goes from BEG0 to END0, but these borders will be moved slightly, to make sure a beginning of line in the first line is included. When NSPACE is non-nil, it indicates the minimum number of spaces that separate columns (default: just one space)." + (interactive "rP") (let* ((beg (min beg0 end0)) (end (max beg0 end0)) (tabsep t) @@ -8569,9 +8550,7 @@ This is being used to correctly align a single field after TAB or RET.") column (indent "") cnt frac rfmt hfmt - (spaces (if (org-in-invisibility-spec-p '(org-table)) - org-table-spaces-around-invisible-separators - org-table-spaces-around-separators)) + (spaces '(1 . 1)) (sp1 (car spaces)) (sp2 (cdr spaces)) (rfmt1 (concat @@ -8585,7 +8564,7 @@ This is being used to correctly align a single field after TAB or RET.") (goto-char beg) (setq links (re-search-forward org-bracket-link-regexp end t)) ;; Make sure the link properties are right FIXME: Can this be optimized???? - (when links (goto-char beg) (while (org-activate-links2 end))) + (when links (goto-char beg) (while (org-activate-bracket-links end))) ;; Check if we are narrowing any columns (goto-char beg) (setq narrow (and org-format-transports-properties-p @@ -8635,12 +8614,9 @@ This is being used to correctly align a single field after TAB or RET.") (loop for xx in column do (when (and (stringp xx) (> (org-string-width xx) fmax)) - (add-text-properties - 0 (length xx) - (list 'help-echo - (concat "Clipped table field, use C-c ` to edit. Full value is:\n" - (copy-sequence xx))) - xx) + (org-add-props xx nil + 'help-echo + (concat "Clipped table field, use C-c ` to edit. Full value is:\n" (copy-sequence xx))) (setq f1 (min fmax (or (string-match org-bracket-link-regexp xx) fmax))) (unless (> f1 1) (error "Cannot narrow field starting with wide link \"%s\"" @@ -8707,8 +8683,6 @@ This is being used to correctly align a single field after TAB or RET.") (set-window-start (selected-window) winstart 'noforce) (org-table-goto-column colpos) (setq org-table-may-need-update nil) - (if (org-in-invisibility-spec-p '(org-table)) - (org-table-add-invisible-to-vertical-lines)) )) (defun org-string-width (s) @@ -9606,49 +9580,6 @@ and end of string." list))) (nreverse list))) -(defun org-table-add-invisible-to-vertical-lines () - "Add an `invisible' property to vertical lines of current table." - (interactive) - (let* ((beg (org-table-begin)) - (end (org-table-end)) - (end1)) - (save-excursion - (goto-char beg) - (while (< (point) end) - (setq end1 (point-at-eol)) - (if (looking-at org-table-dataline-regexp) - (while (re-search-forward "|" end1 t) - (add-text-properties (1- (point)) (point) - '(invisible org-table))) - (while (re-search-forward "[+|]" end1 t) - (add-text-properties (1- (point)) (point) - '(invisible org-table)))) - (beginning-of-line 2))))) - -(defun org-table-toggle-vline-visibility (&optional arg) - "Toggle the visibility of table vertical lines. -The effect is immediate and on all tables in the file. -With prefix ARG, make lines invisible when ARG is positive, make lines -visible when ARG is not positive." - (interactive "P") - (let ((action (cond - ((and arg (> (prefix-numeric-value arg) 0)) 'on) - ((and arg (< (prefix-numeric-value arg) 1)) 'off) - (t (if (org-in-invisibility-spec-p '(org-table)) - 'off - 'on))))) - (if (eq action 'off) - (progn - (org-remove-from-invisibility-spec '(org-table)) - (org-table-map-tables 'org-table-align) - (message "Vertical table lines visible") - (if (org-at-table-p) - (org-table-align))) - (org-add-to-invisibility-spec '(org-table)) - (org-table-map-tables 'org-table-align) - (message "Vertical table lines invisible")) - (redraw-frame (selected-frame)))) - (defun org-table-map-tables (function) "Apply FUNCTION to the start of all tables in the buffer." (save-excursion @@ -10541,12 +10472,12 @@ table editor in arbitrary modes.") (if auto-fill-inhibit-regexp (concat "\\([ \t]*|\\|" auto-fill-inhibit-regexp) "[ \t]*|")) - (org-add-to-invisibility-spec '(org-cwidth . nil)) + (org-add-to-invisibility-spec '(org-cwidth)) (easy-menu-add orgtbl-mode-menu) (run-hooks 'orgtbl-mode-hook)) (setq auto-fill-inhibit-regexp org-old-auto-fill-inhibit-regexp) (org-cleanup-narrow-column-properties) - (org-remove-from-invisibility-spec '(org-cwidth . nil)) + (org-remove-from-invisibility-spec '(org-cwidth)) (remove-hook 'before-change-functions 'org-before-change-function t) (easy-menu-remove orgtbl-mode-menu) (force-mode-line-update 'all)))) @@ -10624,11 +10555,11 @@ to execute outside of tables." '("\C-c?" org-table-current-column) '("\C-c " org-table-blank-field) '("\C-c+" org-table-sum) - '("\C-c|" org-table-toggle-vline-visibility) '("\C-c=" org-table-eval-formula) '("\C-c'" org-table-edit-formulas) '("\C-c`" org-table-edit-field) '("\C-c*" org-table-recalculate) + '("\C-c|" org-table-create-or-convert-from-region) '("\C-c^" org-table-sort-lines) '([(control ?#)] org-table-rotate-recalc-marks))) elt key fun cmd) @@ -11099,6 +11030,8 @@ translations. There is currently no way for users to extend this.") (let* ((cb (current-buffer)) (re-radio (and org-target-link-regexp (concat "\\([^<]\\)\\(" org-target-link-regexp "\\)"))) + (re-plain-link (concat "\\([^[<]\\)" org-plain-link-re)) + (re-angle-link (concat "\\([^[]\\)" org-angle-link-re)) rtn) (save-excursion (set-buffer (get-buffer-create " org-mode-tmp")) @@ -11122,11 +11055,17 @@ translations. There is currently no way for users to extend this.") (goto-char (match-beginning 0))) ;; Normalize links: Convert angle and plain links into bracket links (goto-char (point-min)) - (while (re-search-forward org-external-link-maybe-brackets nil t) + (while (re-search-forward re-plain-link nil t) (replace-match - (concat (if (match-end 1) (match-string 1) "[[") - (match-string 3) ":" (match-string 4) - (if (match-end 5) (match-string 5) "]]")) t t)) + (concat + (match-string 1) "[[" (match-string 2) ":" (match-string 3) "]]") + t t)) + (goto-char (point-min)) + (while (re-search-forward re-angle-link nil t) + (replace-match + (concat + (match-string 1) "[[" (match-string 2) ":" (match-string 3) "]]") + t t)) ;; Remove comments (goto-char (point-min)) @@ -11273,7 +11212,8 @@ underlined headlines. The default is 3." (not (equal (match-string 2 line) org-done-string))) ; TODO, not DONE - (and (= level umax) + (and org-export-mark-todo-in-toc + (= level umax) (org-search-todo-below line lines level)))) (setq txt (org-html-expand-for-ascii txt)) @@ -11651,7 +11591,8 @@ headlines. The default is 3. Lower levels will become bulleted lists." (not (equal (match-string 2 line) org-done-string))) ; TODO, not DONE - (and (= level umax) + (and org-export-mark-todo-in-toc + (= level umax) (org-search-todo-below line lines level)))) (if org-export-with-section-numbers @@ -11791,6 +11732,7 @@ headlines. The default is 3. Lower levels will become bulleted lists." (concat "" desc ""))))) ((member type '("bbdb" "vm" "wl" "mhe" "rmail" "gnus" "shell")) (setq rpl (concat "<" type ":" path ">")))) + ;; FIXME: We get to see the escaped links!!!!! (setq line (replace-match rpl t t line) start (+ start (length rpl)))) ;; TODO items @@ -11850,8 +11792,7 @@ headlines. The default is 3. Lower levels will become bulleted lists." (insert (org-format-table-html table-buffer table-orig-buffer)))) (t ;; Normal lines - (when (and (> org-export-plain-list-max-depth 0) - (string-match + (when (and (string-match (cond ((eq llt t) "^\\([ \t]*\\)\\(\\([-+*]\\)\\|\\([0-9]+[.)]\\)\\)?\\( +[^ \t\n\r]\\|[ \t]*$\\)") ((= llt ?.) "^\\([ \t]*\\)\\(\\([-+*]\\)\\|\\([0-9]+\\.\\)\\)?\\( +[^ \t\n\r]\\|[ \t]*$\\)") @@ -11875,9 +11816,7 @@ headlines. The default is 3. Lower levels will become bulleted lists." (cond ((and starter (or (not in-local-list) - (> ind (car local-list-indent))) - (< (length local-list-indent) - org-export-plain-list-max-depth)) + (> ind (car local-list-indent)))) ;; Start new (level of ) list (insert (if start-is-num "
    \n
  1. \n" "
      \n
    • \n")) (push start-is-num local-list-num) @@ -12061,32 +12000,38 @@ But it has the disadvantage, that Org-mode's HTML conversions cannot be used." s) (defun org-html-expand (string) - "Prepare STRING for HTML export. Applies all active conversions." - ;; First check if there is a link in the line - if yes, apply conversions - ;; only before the start of the link. - ;; FIXME: This is no longer correct, because links now have an end. - (let* ((m (string-match org-link-regexp string)) - (s (if m (substring string 0 m) string)) - (r (if m (substring string m) ""))) - ;; convert & to &, < to < and > to > - (setq s (org-html-protect s)) - (if org-export-html-expand - (while (string-match "@<\\([^&]*\\)>" s) - (setq s (replace-match "<\\1>" nil nil s)))) - (if org-export-with-emphasize - (setq s (org-export-html-convert-emphasize s))) - (if org-export-with-sub-superscripts - (setq s (org-export-html-convert-sub-super s))) - (if org-export-with-TeX-macros - (let ((start 0) wd ass) - (while (setq start (string-match "\\\\\\([a-zA-Z]+\\)" s start)) - (setq wd (match-string 1 s)) - (if (setq ass (assoc wd org-html-entities)) - (setq s (replace-match (or (cdr ass) - (concat "&" (car ass) ";")) - t t s)) - (setq start (+ start (length wd))))))) - (concat s r))) + "Prepare STRING for HTML export. Applies all active conversions. +If there are links in the string, don't modify these." + (let* (m s l res) + (while (setq m (string-match org-bracket-link-regexp string)) + (setq s (substring string 0 m) + l (match-string 0 string) + string (substring string (match-end 0))) + (push (org-html-do-expand s) res) + (push l res)) + (push (org-html-do-expand string) res) + (apply 'concat (nreverse res)))) + +(defun org-html-do-expand (s) + "Apply all active conversions to translate special ASCII to HTML." + (setq s (org-html-protect s)) + (if org-export-html-expand + (while (string-match "@<\\([^&]*\\)>" s) + (setq s (replace-match "<\\1>" nil nil s)))) + (if org-export-with-emphasize + (setq s (org-export-html-convert-emphasize s))) + (if org-export-with-sub-superscripts + (setq s (org-export-html-convert-sub-super s))) + (if org-export-with-TeX-macros + (let ((start 0) wd ass) + (while (setq start (string-match "\\\\\\([a-zA-Z]+\\)" s start)) + (setq wd (match-string 1 s)) + (if (setq ass (assoc wd org-html-entities)) + (setq s (replace-match (or (cdr ass) + (concat "&" (car ass) ";")) + t t s)) + (setq start (+ start (length wd))))))) + s) (defun org-create-multibrace-regexp (left right n) "Create a regular expression which will match a balanced sexp. @@ -12390,7 +12335,6 @@ END:VTODO\n" (name (or name "unknown")) (timezone (cadr (current-time-zone)))) (princ - ;; FIXME: Should we use VERSION 1? MS Outlook would then work, it seems (format "BEGIN:VCALENDAR VERSION:2.0 X-WR-CALNAME:%s @@ -12517,10 +12461,10 @@ a time), or the day by one (if it does not contain a time)." (define-key org-mode-map "\C-c?" 'org-table-current-column) (define-key org-mode-map "\C-c " 'org-table-blank-field) (define-key org-mode-map "\C-c+" 'org-table-sum) -(define-key org-mode-map "\C-c|" 'org-table-toggle-vline-visibility) (define-key org-mode-map "\C-c=" 'org-table-eval-formula) (define-key org-mode-map "\C-c'" 'org-table-edit-formulas) (define-key org-mode-map "\C-c`" 'org-table-edit-field) +(define-key org-mode-map "\C-c|" 'org-table-create-or-convert-from-region) (define-key org-mode-map "\C-c*" 'org-table-recalculate) (define-key org-mode-map [(control ?#)] 'org-table-rotate-recalc-marks) (define-key org-mode-map "\C-c~" 'org-table-create-with-table.el) @@ -12830,8 +12774,6 @@ If the cursor is on a #+TBLFM line, re-apply the formulae to the table." ((and (local-variable-p 'org-finish-function (current-buffer)) (fboundp org-finish-function)) (funcall org-finish-function)) -; ((and (boundp 'remember-buffer) (equal (buffer-name) remember-buffer)) -; (remember-buffer)) ;; FIXME: can we remove this?????? ((org-on-target-p) (org-update-radio-target-regexp)) ((org-on-heading-p) (org-set-tags arg)) ((org-at-table.el-p) @@ -12857,14 +12799,6 @@ If the cursor is on a #+TBLFM line, re-apply the formulae to the table." (if (org-at-table-p) (org-table-recalculate t)))) (t (org-mode-restart)))) - ((org-region-active-p) - (org-table-convert-region (region-beginning) (region-end) arg)) - ((condition-case nil - (and (region-beginning) (region-end)) - (error nil)) - (if (y-or-n-p "Convert inactive region to table? ") - (org-table-convert-region (region-beginning) (region-end) arg) - (error "Abort"))) (t (error "C-c C-c can do nothing useful at this location."))))) (defun org-mode-restart () @@ -12946,12 +12880,9 @@ See the individual commands for more information." (setq org-table-formula-debug (not org-table-formula-debug)) :style toggle :selected org-table-formula-debug] "--" - ["Invisible Vlines" org-table-toggle-vline-visibility - :style toggle :selected (org-in-invisibility-spec-p '(org-table))] - "--" ["Create" org-table-create (and (not (org-at-table-p)) org-enable-table-editor)] - ["Convert Region" org-ctrl-c-ctrl-c (not (org-at-table-p 'any))] + ["Convert Region" org-table-convert-region (not (org-at-table-p 'any))] ["Import from File" org-table-import (not (org-at-table-p))] ["Export to File" org-table-export (org-at-table-p)] "--" @@ -13034,7 +12965,10 @@ See the individual commands for more information." (progn (org-remove-from-invisibility-spec '(org-link)) (org-restart-font-lock)) :style radio :selected (not (member '(org-link) buffer-invisibility-spec))] - ) + "--" + ["Upgrade all to [[link][desc]]" org-upgrade-old-links + (save-excursion (goto-char (point-min)) + (re-search-forward "<[a-z]+:" nil t))]) "--" ("Export" ["ASCII" org-export-as-ascii t] @@ -13057,7 +12991,7 @@ See the individual commands for more information." ("Customize" ["Browse Org Group" org-customize t] "--" - ["Build Full Customize Menu" org-create-customize-menu + ["Expand This Menu" org-create-customize-menu (fboundp 'customize-menu-create)]) "--" ["Refresh setup" org-mode-restart t] @@ -13482,31 +13416,30 @@ Show the heading too, if it is currently invisible." (run-hooks 'org-load-hook) ;; Experimental code +;; FIXME: Move this code when it is ready. -(defun org-upgrade-old-links (&optional broken-only) +(defun org-upgrade-old-links (&optional query-description) "Transfer old <...> style links to new [[...]] style links. -With arg BROKEN-ONLY, fix only the links that contain space characters -and therefore have stopped working in this new version." - (interactive "P") +With arg query-description, ask at each match for a description text to use +for this link." + (interactive (list (y-or-n-p "Would you like to be queried for a description at each link?"))) (save-excursion (goto-char (point-min)) (let ((re (concat "\\([^[]\\)<\\(" "\\(" (mapconcat 'identity org-link-types "\\|") "\\):" "[^" org-non-link-chars "]+\\)>")) - l1 l2) + l1 l2 (cnt 0)) (while (re-search-forward re nil t) - (setq l1 (match-string 2) - l2 (save-match-data - (org-link-escape (match-string 2)))) - (when (or (not broken-only) - (save-match-data (string-match " " l1))) - (if (equal l1 l2) - (replace-match (concat (match-string 1) "[[" l1 "]]") t t) - (replace-match - (concat (match-string 1) "[[" l2 "][" l1 "]]") - t t))))))) - + (setq cnt (1+ cnt) + l1 (org-match-string-no-properties 2) + l2 (save-match-data (org-link-escape l1))) + (when query-description (setq l1 (read-string "Desc: " l1))) + (if (equal l1 l2) + (replace-match (concat (match-string 1) "[[" l1 "]]") t t) + (replace-match (concat (match-string 1) "[[" l2 "][" l1 "]]") t t))) + (message "%d matches have beed treated" cnt)))) + (defun org-export-as-xml () "Export current buffer as XOXO XML buffer." (interactive) diff --git a/org.pdf b/org.pdf index 0bb63de3e..866916b9c 100644 Binary files a/org.pdf and b/org.pdf differ diff --git a/org.texi b/org.texi index c5875445b..16644f7df 100644 --- a/org.texi +++ b/org.texi @@ -4,8 +4,8 @@ @c @setfilename ../info/org @settitle Org Mode Manual -@set VERSION 4.19b -@set DATE March 2006 +@set VERSION 4.20 +@set DATE April 2006 @dircategory Emacs @direntry @@ -311,12 +311,6 @@ MY PROJECTS -*- mode: org; -*- the file's name is. See also the variable @code{org-insert-mode-line-in-empty-file}. -If you are upgrading to version 4.20 or later from a version 4.14 or -earlier, some links may stop working. These are links containing space -characters. To make such links work again, and also to transform all -links from the old @samp{} format to the new @samp{[[link]]} -format, execute once in each file: @kbd{M-x org-upgrade-old-links}. - @node Feedback, , Installation and activation, Introduction @section Feedback @cindex feedback @@ -786,18 +780,16 @@ unpredictable for you, configure the variables @table @kbd @tsubheading{Creation and conversion} -@item M-x org-table-create -Creates an empty Org-mode table. However, it is much easier to just -start typing, like @kbd{|Name|Phone|Age @key{RET} |- @key{TAB}} - -@kindex C-c C-c -@item C-c C-c -Convert region to table. Works when the cursor is not in an existing -table, and when there is a region defined. If every line contains at -least one TAB character, the function assumes that the material is tab -separated. If not, lines are split at whitespace into fields. You -can use a prefix argument to indicate the minimum number of consequtive -spaces required to indentify a field separator (default: just one). +@kindex C-c | +@item C-c | +Convert the active region to table. If every line contains at least one +TAB character, the function assumes that the material is tab separated. +If not, lines are split at whitespace into fields. You can use a prefix +argument to indicate the minimum number of consequtive spaces required +to indentify a field separator (default: just one).@* +If there is no active region, this command creates an empty Org-mode +table. However, it's easier to just start typing, like +@kbd{|Name|Phone|Age @key{RET} |- @key{TAB}}. @tsubheading{Re-aligning and field motion} @kindex C-c C-c @@ -958,12 +950,6 @@ edited in place. This is an alias for @kbd{C-u C-c `} to make the current field fully visible. -@kindex C-c | -@item C-c | -Toggle the visibility of vertical lines in tables. The lines are -still there, only made invisible with a text property. Any @samp{|} -added by hand will become invisible on the next align. - @item M-x org-table-import Import a file as a table. The table should be TAB- or whitespace separated. Useful, for example, to import an Excel table or data from a @@ -1381,28 +1367,30 @@ links to other files, Usenet articles, emails and much more. @cindex link format @cindex format, of links -Org-mode will recognize plain URL-like links in the buffer and activate -them as clickable links. However, the general linkformat looks like -this: +Org-mode will recognize plain URL-like links and activate them as +clickable links. However, the general linkformat looks like this: @example [[link][description]] @r{or alternatively} [[link]] @end example -The description part is optional. Once a link in the buffer is -complete, Org-mode will change the display so that -@u{@samp{description}} is displayed instead of -@samp{[[link][description]]} and @samp{link} is displayed instead of +Once a link in the buffer is complete (all brackets present), Org-mode +will change the display so that @samp{description} is displayed instead +of @samp{[[link][description]]} and @samp{link} is displayed instead of @samp{[[link]]}. Links will be highlighted in the face @code{org-link}, which by default is an underlined face. You can directly edit the -visible part of a link. To edit the invisible part, use @kbd{C-c C-l} -with the cursor on the link. If you place the cursor at the beginning -of end of the displayed text and press @key{BACKSPACE}, you will remove -the (invisible) bracket at that location. This makes the link incomplete +visible part of a link. Note that this can be either the @samp{link} +part (if there is not description) or the @samp{description} part. To +edit also the invisible @samp{link} part, use @kbd{C-c C-l} with the +cursor on the link. + +If you place the cursor at the beginning or just behind the end of the +displayed text and press @key{BACKSPACE}, you will remove the +(invisible) bracket at that location. This makes the link incomplete and the internals are again displayed as plain text. Inserting the -missing bracket does hide the link internal again. Finally, you may also -use the menu entry @code{Org->Hperlinks->Literal links} to unhide all -links. +missing bracket does hide the link internals again. To show the +internal structure of all links, use the menu entry +@code{Org->Hyperlinks->Literal links}. @node Internal links, External links, Link format, Hyperlinks @section Internal links @@ -1473,15 +1461,10 @@ 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. It is mainly kept for backward compatibility, but the use is -deprecated. To activate CamelCase words as links, and to make headline -completion offer CamelCase version of headlines, the following -customization is needed: - -@lisp -(setq org-activate-camels t - org-file-link-context-use-camel-case t) -@end lisp +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]]}. @node External links, Managing links, Internal links, Hyperlinks @section External links @@ -1521,7 +1504,7 @@ rmail:folder#id @r{RMAIL message link} gnus:group @r{GNUS group link} gnus:group#id @r{GNUS article link} bbdb:Richard Stallman @r{BBDB link} -shell:ls *.org@footnote{Note that @samp{<} and @samp{>} cannot be part of a link, and therefore of a shell command. If you need redirection, use @@@{ and @@@} instead.} @r{A shell command} +shell:ls *.org @r{A shell command} @end example A link should be enclosed in double brackets and may contain a @@ -1535,8 +1518,9 @@ format}), for example: @cindex angular brackets, around links @cindex plain text external links Org-mode also finds external links in the normal text and activates them -as links. Plain text links cannot contain spaces. To remove -ambiguities about the end of the link, enclose them in angular brackets. +as links. If spaces must be part of the link (for example in +@samp{bbdb:Richard Stallman}) or to remove ambiguities about the end of +the link, enclose them in angular brackets. @node Managing links, Search Options, External links, Hyperlinks @section Managing links @@ -1550,16 +1534,15 @@ insert it into an org-mode file, and to follow the link. @item C-c l Store a link to the current location. This is a @emph{global} command which can be used in any buffer to create a link. The link will be -stored for later insertion into an Org-mode buffer (see below). For -VM, RMAIL, WANDERLUST, GNUS and BBDB buffers, the link will point to -the current article/entry. For W3 and W3M buffers, the link goes to -the current URL. For Org-mode files, the current headline is -targeted. For any other files, the link will point to the file, with -a search string (@pxref{Search Options}) pointing to the -contents of the current line. If there is an active region, the -selected words will form the basis of the search string. The key -binding @kbd{C-c l} is only a suggestion - see @ref{Installation and -activation}. +stored for later insertion into an Org-mode buffer (see below). For VM, +RMAIL, WANDERLUST, MH-E, GNUS and BBDB buffers, the link will point to +the current article/entry. For W3 and W3M buffers, the link goes to the +current URL. For Org-mode files, the current headline is targeted. For +any other files, the link will point to the file, with a search string +(@pxref{Search Options}) pointing to the contents of the current line. +If there is an active region, the selected words will form the basis of +the search string. The key binding @kbd{C-c l} is only a suggestion - +see @ref{Installation and activation}. @kindex C-c C-l @cindex link completion @@ -1697,11 +1680,11 @@ package.} will tell @emph{Remember} to use org files as target, and to create annotations compatible with Org-mode links. @example +(setq org-directory "~/path/to/my/orgfiles/") +(setq org-default-notes-file "~/.notes") (autoload 'org-remember-annotation "org") (autoload 'org-remember-apply-template "org") (autoload 'org-remember-handler "org") -(setq org-directory "~/path/to/my/orgfiles/") -(setq org-default-notes-file "~/.notes") (setq remember-annotation-functions '(org-remember-annotation)) (setq remember-handler-functions '(org-remember-handler)) (add-hook 'remember-mode-hook 'org-remember-apply-template) @@ -1720,9 +1703,9 @@ journal entries, you could use: @end example @noindent In these entries, the character specifies how to select the -template, the first string specifies the template, and the second string -specifies a default file (overruling @code{org-default-notes-file}) as a -target for this note. +template, the first string specifies the template, and the (optional) +second string specifies a default file (overruling +@code{org-default-notes-file}) as a target for this note. When you call @kbd{M-x remember} to remember something, org will prompt for a key to select the template and then prepare the buffer like @@ -1742,12 +1725,12 @@ for a key to select the template and then prepare the buffer like @noindent See the variable @code{org-remember-templates} for more details. When you are finished composing a note with remember, you have to press -@kbd{C-c C-c} to exit remember-mode and to file the note away. The -handler first prompts for a target file - if you press @key{RET}, the -value of @code{org-default-notes-file} is used. Then the command offers -the headings tree of the selected file. You can either immediately -press @key{RET} to get the note appended to the file. Or you can use -vertical cursor motion (@key{up} and @key{down}) and visibility cycling +@kbd{C-c C-c} to file the note away. The handler first prompts for a +target file - if you press @key{RET}, the value of +@code{org-default-notes-file} is used. Then the command offers the +headings tree of the selected file. You can either immediately press +@key{RET} to get the note appended to the file. Or you can use vertical +cursor motion (@key{up} and @key{down}) and visibility cycling (@key{TAB}) to find a better place. Pressing @key{RET} or @key{left} or @key{right} leads to the following result. @@ -2796,7 +2779,7 @@ original org file. @kindex T @item T -Show all tags assiciated with the current item. Because of +Show all tags associated with the current item. Because of inheritance, this may be more than the tags listed in the line itself. @kindex : @@ -2866,7 +2849,7 @@ date at the cursor. @kindex M @item M -Show the phases of the moon for the three month around current date. +Show the phases of the moon for the three months around current date. @kindex S @item S @@ -3401,45 +3384,75 @@ rather use @kbd{C-c .} to re-insert the timestamp. @enumerate @item @b{Org-mode seems to be a useful default mode for the various @file{README} files I have scattered through my directories. How do I -turn it on for all @file{README} files?} +turn it on for all @file{README} files?}@* +@c @example (add-to-list 'auto-mode-alist '("README$" . org-mode)) @end example @item @b{Some of my links stopped working after I upgraded to a version -4.20 or later. Why is this, and how can I fix it?}@* The newer versions of -Org-mode have a better link system and no longer allow unescaped space -characters as part of a link. To fix these links, and also to move all -@samp{} style links to the new @samp{[[link]]} system, execute -once in each Org-mode file: @kbd{M-x org-upgrade-old-links}. +4.20 or later. Why is this, and how can I fix it?}@* +@c +These must be links in plain text, containing white space, such as +@samp{bbdb:Richard Stallman}. You need to protect these links by +putting double brackets around them, like @samp{[[bbdb:Richard +Stallman]]}. -@item @b{I really like the old style links with angular brackets -better. Please give them back to me, don't tell me it is not -possible!}@* Would I let you down like that? If you must (even if I -don't understand why), you can do this +@item @b{I see that Org-mode now creates links using the double bracket +convention that hides the link part and the brackets, only showing the +description part. How can I convert my old links to this new format?}@* +@c +Execute once in each Org-mode file: @kbd{M-x org-upgrade-old-links}. +The replaces angular brackets with the link format. + +@item @b{I don't care if you find the new bracket links great, I am +attached to the old style using angular brackets and no hiding of the +link text. Please give them back to me, don't tell me it is not +possible!}@* +@c +Would I let you down like that? If you must (even if I don't understand +why), you can do this @lisp -(setq org-allow-space-in-plain-links t - org-link-style 'plain +(setq org-link-style 'plain org-link-format "<%s>") @end lisp +@item @b{When I am executing shell links I always get a +confirmation prompt and need to type @kbd{yes @key{RET}}, thats 4 key +presses! Can I get rid of this?}@* +@c +@cindex shell links, confirmation +@cindex dangerous commands +The confirmation is there to protect you from unwantingly execute +potentially dangerous commands. For example, imagine a link +@samp{[[shell:rm -rf ~/*][Google Search]]}. In an Org-mode buffer, this +command would look like @samp{Google Search}, but really it would remove +your home directory. If you wish, you can make it easier to respond to +the query by setting @code{org-confirm-shell-links} to @code{y-or-n-p}. +Then a single @kbd{y} keypress will be enough to confirm shell links. +It is also possible to turn off this check entirely, but I do not +recommend to do this. Be warned. + @item @b{All these stars are driving me mad, I just find the Emacs outlines unreadable. Can't you just put white space and a single star as a starter for headlines?}@* +@c See @ref{Clean view}. @item @b{I would like to have two windows on the same Org-mode file, but with different outline visibility. Is that possible?}@* +@c @cindex @code{make-indirect-buffer} @cindex indirect buffers -In GNU Emacs, you may use @emph{indirect buffers} which do exactly -this. See the documentation on the command -@code{make-indirect-buffer}. In XEmacs, this is currently not -possible because of the different outline implementation. +In GNU Emacs, you may use @emph{indirect buffers} which do exactly this. +See the documentation on the command @code{make-indirect-buffer}. In +XEmacs, this is currently not possible because of the different outline +implementation. @item @b{When I export my TODO list, every TODO item becomes a separate section. How do I enforce these items to be exported as an itemized list?}@* +@c If you plan to use ASCII or HTML export, make sure things you want to be exported as item lists are level 4 at least, even if that does mean there is a level jump. For example: @@ -3459,7 +3472,9 @@ configure the @samp{H} switch. +OPTIONS: H:2; ... @end example -@item @b{I would like to export only a subtree of my file to HTML. How?}@* +@item @b{I would like to export only a subtree of my file to HTML. +How?}@* +@c @cindex exporting a subtree If you want to export a subtree, mark the subtree as region and then export. Marking can be done with @kbd{C-c @@ C-x C-x}, for example. @@ -3468,16 +3483,9 @@ export. Marking can be done with @kbd{C-c @@ C-x C-x}, for example. CUA-mode, is there a way to fix this conflict?}@* Yes, see @ref{Interaction}. -@item @b{Is there an easy way to insert an empty table template with a -default number of rows and columns?}@* -@cindex table, empty template -To insert an empty table template, just type @samp{|-} and use -@key{TAB}. The default size can be changed with the variable -@code{org-table-default-size}. However, just starting to type the -first line is usually much easier. - @item @b{One of my table columns has started to fill up with @samp{#ERROR}. What is going on?}@* +@c Org-mode tried to compute the column from other fields using a formula stored in the @samp{#+TBLFMT:} line just below the table, and the evaluation of the formula fails. Fix the fields used in the @@ -3487,17 +3495,20 @@ formula, or fix the formula, or remove it! horizontal line in the table, pressing TAB creates a new table line @i{before} the horizontal line. How can I quickly move to the line @i{below} the horizontal line instead?}@* +@c Press @key{down} (to get on the separator line) and then @key{TAB}. Or configure the variable @code{org-table-tab-jumps-over-hlines}. @item @b{How can I change the indentation of an entire table without fixing every line by hand?}@* +@c @cindex indentation, of tables The indentation of a table is set by the first line. So just fix the indentation of the first line and realign with @key{TAB}. @item @b{Is it possible to include entries from org-mode files into my emacs diary?}@* +@c Since the org-mode agenda is much more powerful and can contain the diary (@pxref{Calendar/Diary integration}), you should think twice before deciding to do this. Integrating Org-mode information into the diff --git a/orgcard.pdf b/orgcard.pdf index 82d95603d..c78e6c108 100644 Binary files a/orgcard.pdf and b/orgcard.pdf differ diff --git a/orgcard.tex b/orgcard.tex index 0a7644293..4c801030d 100644 --- a/orgcard.tex +++ b/orgcard.tex @@ -1,5 +1,5 @@ % Reference Card for Org Mode -\def\orgversionnumber{4.19b} +\def\orgversionnumber{4.20} \def\year{2006} % %**start of header @@ -427,9 +427,8 @@ To set archive location for current file, add a line like$^3$: %\metax{insert a new Org-mode table}{M-x org-table-create} \metax{just start typing, e.g.}{|Name|Phone|Age RET |- TAB} -\key{convert region to table}{C-c C-c} -\key{... separator at least 3 spaces}{C-3 C-c C-c} -%\key{... prompt for separator regexp}{C-u C-c C-c} +\key{convert region to table}{C-c |} +\key{... separator at least 3 spaces}{C-3 C-c |} {\bf Commands available inside tables} @@ -465,9 +464,7 @@ Outside of tables, the same keys may have other functionality. \key{paste rectangular region}{C-c C-x C-y} \key{fill paragraph across selected cells}{C-c C-q} -{\bf Calculations} - -These need the Emacs calc package installed. +{\bf Calculations} (in combination with Emacs \kbd{calc} package) \key{set and eval column formula}{C-c =} \key{set and eval named-field formula}{C-u C-c =} @@ -475,8 +472,8 @@ These need the Emacs calc package installed. \key{re-apply all stored equations to current line}{C-c *} \key{re-apply all stored equations to entire table}{C-u C-c *} -\kbd{TAB}, \kbd{RET} and \kbd{C-c C-c} trigger automatic recalculation -in lines starting with: {\tt | \# |}. +%\kbd{TAB}, \kbd{RET} and \kbd{C-c C-c} trigger automatic recalculation +%in lines starting with: {\tt | \# |}. \key{rotate calculation mark through \# * ! \^ \_ \$}{C-\#} @@ -496,9 +493,9 @@ formula, \kbd{:=} a named-field formula. {\bf Miscellaneous} +\key{to limit column width to \kbd{N} characters, use}{...| |...} \key{edit the current field in a separate window}{C-c `} \key{make current field fully visible}{C-u TAB} -\key{toggle visibility of vertical lines}{C-c |} \metax{export as tab-separated file}{M-x org-table-export} \metax{import tab-separated file}{M-x org-table-import}