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:
"\\(" (mapconcat 'identity org-link-types "\\|") "\\):"
"\\([^" org-non-link-chars " ]"
"[^" org-non-link-chars "]*"
- "[^" org-non-link-chars " ]\\)>?"))
-(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
"\\(" (mapconcat 'identity org-link-types "\\|") "\\):"
- "\\([^" org-non-link-chars " ]+\\)>?"))
-(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
\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}