summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorNicolas Goaziou <mail@nicolasgoaziou.fr>2019-03-10 14:49:18 +0100
committerNicolas Goaziou <mail@nicolasgoaziou.fr>2019-03-10 18:00:36 +0100
commit1c936fd2aceada93dc0c8736287c1e117f7dd0ee (patch)
treed65b1c65636c9767fbe543b8eaa89361cce2256c
parent2b00d6281606ef295dadbe4ddd929ebdd6716d60 (diff)
downloadorg-mode-1c936fd2aceada93dc0c8736287c1e117f7dd0ee.tar.gz
org-manual: Document new link syntax
* doc/org-manual.org (Link Format): Document rules for escaping sensitive characters in a link.
-rw-r--r--doc/org-manual.org27
-rw-r--r--etc/ORG-NEWS31
2 files changed, 44 insertions, 14 deletions
diff --git a/doc/org-manual.org b/doc/org-manual.org
index 50ec587..acf973d 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -3022,18 +3022,23 @@ or alternatively
: [[LINK]]
-#+cindex: square brackets in links
#+cindex: escape syntax, for links
-The {{{var(LINK)}}} part cannot contain =[= and =]= characters. You
-can replace them with their percent-encoded counterparts, which are,
-respectively, =%5B= and =%5D=. You also need to encode =%= characters
-as =%25=. Optionally, it may also come handy to encode consecutive
-spaces as =%20=.
-
-Org takes for granted that such links are correctly escaped. Luckily,
-functions inserting links (see [[*Handling Links]]) take care of this.
-You really need to bother about it only when inserting manually a URI
-within square brackets.
+Some =\= and =]= characters in the {{{var(LINK)}}} part need to be
+"escaped", i.e., preceded by another =\= character. More
+specifically, the following character categories must be escaped, in
+order:
+
+1. all consecutive =\= characters at the end of the link;
+2. any =]= character at the very end of the link;
+3. any =]= character followed by either =[= or =]=;
+
+#+findex: org-link-escape
+Org takes for granted that such links are correctly escaped.
+Functions inserting links (see [[*Handling Links]]) take care of this.
+You only need to bother about those rules when inserting directly, or
+yanking, a URI within square brackets. When in doubt, use the
+function ~org-link-escape~ in order to turn a link string into its
+properly escaped form.
Once a link in the buffer is complete, with all brackets present, Org
changes the display so that =DESCRIPTION= is displayed instead of
diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index cd5e4d9..102f52b 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -13,10 +13,35 @@ Please send Org bug reports to mailto:emacs-orgmode@gnu.org.
* Version 9.3
** Incompatible changes
-*** ob-clojure will not auto prepend ~(ns ..)~ statement now
-When tangling, user usually just want to tangle literally code instead
+*** Change bracket link escaping syntax
+
+Org used to percent-encode sensitive characters in the URI part of the
+bracket links.
+
+Now, escaping mechanism uses the usual backslash character, according
+to the following rules, applied in order:
+
+1. All consecutive =\= characters at the end of the link must be
+ escaped;
+2. Any =]= character at the very end of the link must be escaped;
+3. Any =]= character followed by either =[= or =]= must be escaped;
+4. Others =]= and =\= characters need not be escaped.
+
+When in doubt, use the function ~org-link-escape~ in order to turn
+a link string into its properly escaped form.
+
+The old ~org-link-escape~ and ~org-link-unescape~ functions have been
+renamed into ~org-link-encode~ and ~org-link-decode~.
+
+*** Change match group number in ~org-link-bracket-re~
+
+Link description, if any, is located in match group 2 instead of match
+group 3.
+
+*** ob-clojure does not auto prepend ~(ns ..)~ statement anymore
+When tangling, user usually just wants to tangle literally code instead
of prepend inserting a ~(ns ..)~ statement before source block
-code. Now, when you have no ~:ns~ header argument specified, this
+code. Now, when you have no ~:ns~ header argument specified, this
behavior will not happend automatically.
*** Change in behavior on exit from an Org edit buffer
Org will no longer attempt to restore the window configuration in the