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

Reply via email to