mirrors
/
org-mode
mirror of https://git.savannah.gnu.org/git/emacs/org-mode.git
0
0
Fork 1
Code Releases Activity

org-manual: Document new link syntax 

* doc/org-manual.org (Link Format): Document rules for escaping
  sensitive characters in a link.
This commit is contained in:
Nicolas Goaziou 2019-03-10 14:49:18 +01:00
parent 2b00d62816
commit 1c936fd2ac
2 changed files with 43 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
doc/org-manual.org
View File

@ -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

31
etc/ORG-NEWS
View File

@ -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