Dear Sir/Madam,
I would like to submit the attached patch improving the documentation
for `org-link-parameters', with small related changes to
`org-link-set-parameters' and the manual (just a missing -s).
Attending one of Protesilaos live streams I found the docstring for
`org-link-parameters' confusing. Investigating deeper, I discovered
that some keyword descriptions did not match the code as of Org 9.8.10.
Specifically, I found that:
- The `:complete' docstring says the function inserts a link and takes
one optional prefix argument. In fact,
`org-link--try-special-completion' calls it with no argument and
uses its return value as the link. This is correctly described in
the manual (section "Link Abbreviations").
- The `:help-echo' docstring says the function is called with one
argument, the help string. From my understanding, however, the
function itself becomes the `help-echo' text property as specified
in the Elisp manual ((elisp) Special Properties), which is called
with the arguments WINDOW, OBJECT and POS.
- The `:htmlize-link' docstring says the value can be a function or a
plist. But I think `org-activate-links' only accepts a function and
replaces any other value with the default.
Furthermore, I changed some of the documentation to improve clarity.
This is, of course, a matter of personal taste. But I do believe that
this is of value. Specifically:
- `:display': Prot himself was confused by this during the livestream,
as it is easy to read this as a face. The patch explains that the
value becomes the `invisible' property of the hidden parts of a
bracket link. So `org-link' (the default) follows
`org-toggle-link-display', and `full' (or any symbol not in
`buffer-invisibility-spec') always displays the full link. I don't
fully understand font-locking; thus I might be wrong, but I believe
that `:display' could be improved by having three values: 'folded
(always folded, ignore `org-toggle-link-display'), 'full (as now),
'adapt or nil (follow `org-toggle-link-display'). I can propose a
code patch for this if you consider it valuable.
- `:export': States that the function returns the exported link as
a string, that the backend is passed as a symbol, and that the
channel may be nil. Also points to `org-link-doi-export' as an
example.
- `:preview': Says the function is run by `org-link-preview' and
names the third argument more precisely.
- `:store': States the argument directly instead of only pointing to
`org-store-link-functions'.
- `:help-echo' and `:htmlize-link': Document the defaults, which
use the link with abbreviations expanded.
- The header now recommends `org-link-set-parameters' over setting
the variable directly.
The patch also lists the reserved link types ("coderef", "custom-id",
"fuzzy" and "radio") in the docstring of `org-link-set-parameters',
which already refuses them. And it fixes a typo in the manual, where
`org-link-set-parameter' should be `org-link-set-parameters'.
make compile and make test pass.
I based the patch on the bugfix branch. Please tell me if you would
prefer it on main.
In the spirit of transparency: I am more used to the GitHub workflow
for contributions, so I used an LLM (Claude Code, Opus 5.5) to
understand how to submit the patch, run the build and tests, and
format and correct my prose. I am aware of the current policy on
LLM-generated patches, so please let me know if this is a problem.
Since the patch is larger than the 15-line limit, I think I might need
an FSF copyright assignment, which I do not have. I would be happy to
complete the assignment process, but I would appreciate some help or
guidance with it.
Thank you in advance for your time.
Have a great day!
Best regards,
Marco Prevedello
From a96ed06a60fca08d7153d25468190d298a361257 Mon Sep 17 00:00:00 2001
Message-ID: <a96ed06a60fca08d7153d25468190d298a361257.1794935960.git.marco.prevede...@outlook.it>
From: Marco Prevedello <[email protected]>
Date: Tue, 17 Nov 2026 18:14:08 +0100
Subject: [PATCH] lisp/ol.el (org-link-parameters): Fix and clarify docstring
* lisp/ol.el (org-link-parameters): Recommend
`org-link-set-parameters'. Fix the documented signatures of
`:complete' and `:help-echo'. Do not document a plist value for
`:htmlize-link', which was never supported. Clarify `:display',
`:export', `:follow', `:preview' and `:store'. Document the defaults
of `:help-echo' and `:htmlize-link'.
* lisp/ol.el (org-link-set-parameters): List the reserved link types.
* doc/org-manual.org (Link Abbreviations): Fix the name of
`org-link-set-parameters'.
---
doc/org-manual.org | 2 +-
lisp/ol.el | 69 ++++++++++++++++++++++++++++++----------------
2 files changed, 46 insertions(+), 25 deletions(-)
diff --git a/doc/org-manual.org b/doc/org-manual.org
index cbfc72c5d..27f225855 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -3826,7 +3826,7 @@ ** Link Abbreviations
the link completion function like this:
#+begin_src emacs-lisp
-(org-link-set-parameter "type" :complete #'some-completion-function)
+(org-link-set-parameters "type" :complete #'some-completion-function)
#+end_src
** Search Options in File Links
diff --git a/lisp/ol.el b/lisp/ol.el
index 24ac9deb1..e1a306d59 100644
--- a/lisp/ol.el
+++ b/lisp/ol.el
@@ -99,6 +99,9 @@ (defgroup org-link nil
(defcustom org-link-parameters nil
"Alist of properties that defines all the links in Org mode.
+Use `org-link-set-parameters' to define a link type or to change
+its properties, rather than setting this variable directly.
+
The key in each association is a string of the link type.
Subsequent optional elements make up a property list for that
type.
@@ -111,27 +114,29 @@ (defcustom org-link-parameters nil
Function used to follow the link, when the `org-open-at-point'
command runs on it. It is called with two arguments: the path,
- as a string, and a universal prefix argument.
+ as a string, and the prefix argument passed to `org-open-at-point'.
Here, you may use `org-link-open-as-file' helper function for
types similar to \"file\".
`:export'
- Function that accepts four arguments:
+ A function that returns the exported link, as a string, and
+ accepts four arguments:
- the path, as a string,
- the description as a string, or nil,
- - the export backend,
- - the export communication channel, as a plist.
+ - the export backend, as a symbol (e.g., `html'),
+ - the export communication channel, as a plist, or nil.
When nil, export for that type of link is delegated to the
- backend.
+ backend. See `org-link-doi-export' as an example.
`:store'
- Function responsible for storing the link. See the function
- `org-store-link-functions' for a description of the expected
- arguments.
+ Function responsible for storing the link. It is called with
+ one argument, non-nil when `org-store-link' is called
+ interactively. See the function `org-store-link-functions' for
+ a description of the expected return value.
Additional properties provide more specific control over the
link.
@@ -147,8 +152,11 @@ (defcustom org-link-parameters nil
`:complete'
- Function that inserts a link with completion. The function
- takes one optional prefix argument.
+ Function that prompts for a link with completion. The function
+ is called with no argument, and should return the full link,
+ including the type prefix, as a string. See
+ `org-link-complete-file' and `org-attach-complete-link' as
+ examples.
`:insert-description'
@@ -165,9 +173,13 @@ (defcustom org-link-parameters nil
`:display'
- Value for `invisible' text property on the hidden parts of the
- link. The most useful value is `full', which will not fold the
- link in descriptive display. Default is `org-link'.
+ Value for the `invisible' text property on the hidden parts of
+ a bracket link (the brackets and the link itself, but not its
+ description). The value `full', or any symbol not in
+ `buffer-invisibility-spec', will make the link always display
+ in full. The default value `org-link' hides the hidden parts
+ of the link when `org-link-descriptive' is non-nil, so that the
+ link follows `org-toggle-link-display'.
`:face'
@@ -178,11 +190,12 @@ (defcustom org-link-parameters nil
`:preview'
- Function to run to generate an in-buffer preview for the link. It
- must accept three arguments:
- - an overlay placed from the start to the end of the link
- - the link path, as a string
- - the syntax node for the link
+ Function run by `org-link-preview' to generate an in-buffer
+ preview for the link. It must accept three arguments:
+ - an overlay placed from the start to the end of the link,
+ - the link path, as a string,
+ - the syntax node for the link, as returned by
+ `org-element-context'.
This function must return a non-nil value to indicate success.
A return value of nil implies that the preview failed, and the
@@ -191,15 +204,21 @@ (defcustom org-link-parameters nil
`:help-echo'
String or function used as a value for the `help-echo' text
- property. The function is called with one argument, the help
- string to display, and should return a string.
+ property. The function is called with three arguments, the
+ window, the object and the position, and should return a
+ string or nil (for no help). See Info node
+ `(elisp) Special Properties'.
+
+ Default is \"LINK: \" followed by the link, with abbreviations
+ expanded.
`:htmlize-link'
- Function or plist for the `htmlize-link' text property. The
- function takes no argument.
+ Function returning a plist for the `htmlize-link' text property.
+ The function takes no argument.
- Default is (:uri \"type:path\")
+ Default is (:uri LINK), where LINK is the link, with
+ abbreviations expanded.
`:keymap'
@@ -1247,7 +1266,9 @@ (defun org-link-get-parameter (type key)
(defun org-link-set-parameters (type &rest parameters)
"Set link TYPE properties to PARAMETERS.
PARAMETERS should be keyword value pairs. See
-`org-link-parameters' for supported keys."
+`org-link-parameters' for supported keys.
+The types \"coderef\", \"custom-id\", \"fuzzy\",
+and \"radio\" are reserved and cannot be defined."
(when (member type '("coderef" "custom-id" "fuzzy" "radio"))
(error "Cannot override reserved link type: %S" type))
(let ((data (assoc type org-link-parameters)))
--
2.54.0