From 1c936fd2aceada93dc0c8736287c1e117f7dd0ee Mon Sep 17 00:00:00 2001
From: Nicolas Goaziou <mail@nicolasgoaziou.fr>
Date: Sun, 10 Mar 2019 14:49:18 +0100
Subject: [PATCH] org-manual: Document new link syntax

* doc/org-manual.org (Link Format): Document rules for escaping
  sensitive characters in a link.
---
 doc/org-manual.org | 25 +++++++++++++++----------
 etc/ORG-NEWS       | 31 ++++++++++++++++++++++++++++---
 2 files changed, 43 insertions(+), 13 deletions(-)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index 50ec587ba..acf973d13 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=.
+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:
 
-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.
+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 cd5e4d900..102f52b0b 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