[RFC][PATCH] Allow to export to ascii custom link types as notes

[RFC][PATCH] Allow to export to ascii custom link types as notes

[Max Nikulin]

[-- Attachment #1: Type: text/plain, Size: 1518 bytes --]

Hi,

In the following thread

Ihor Radchenko. Re: Exporting elisp: and shell: links.
Sat, 14 Oct 2023 08:13:35 +0000.
https://list.orgmode.org/87wmvp1v0w.fsf@localhost

it was discussed that attempts to customize export to plain text of link 
types such as "elisp:" and "shell:" break formatting as notes at the end 
of the heading (`org-ascii-links-to-notes').

The attached patches is a draft implementing this feature (new functions 
are not documented yet).

For ascii backend :export function from `org-link-parameters' may return 
(PATH . DESCRIPTION) `cons' instead of string. Depending on chosen link 
style it will be exported as "[DESCRIPTION]" with the "[DESCRIPTION] 
PATH" note at the end of heading or as the inline reference "DESCRIPTION 
(PATH)".

I believe that parenthesis should be skipped in the case of angle 
brackets "(<URI>)", but I do not change this behavior. There is some 
inconsistency in respect to brackets for description of inline links, 
but it is preserved as well.

I do not like that :export functions are called twice: for text and for 
note. In my opinion it is better to collect links in a property of INFO 
to later format notes at the end of the heading. I would consider more 
dense style of notes with list markers instead of empty line as separator.

Namely "shell:" and "elisp:" links may be exported as notes in the 
current Org version since they have no :export property. The proposed 
feature allows to have custom :export e.g. to not add "shell:" prefix to 
the code.

[-- Attachment #2: 0001-test-ox-ascii.el-Test-custom-links.patch --]
[-- Type: text/x-patch, Size: 4747 bytes --]

From 8a80605e608809fa450ee08d2601a0c7a27c5276 Mon Sep 17 00:00:00 2001
From: Max Nikulin <manikulin@gmail.com>
Date: Fri, 20 Oct 2023 17:10:36 +0700
Subject: [PATCH 1/3] test-ox-ascii.el: Test custom links

* testing/lisp/test-ox-ascii.el (test-ox-ascii--restore-syntax)
(test-ox-ascii--link-export-inline): Helper functions.
(test-ox-ascii/link-custom-protocol-fallback)
(test-ox-ascii/link-custom-protocol-string): Test export of custom link
types having the :export parameters or relying on format provided by
default when `org-ascii-links-to-notes' enabled or disabled.
---
 testing/lisp/test-ox-ascii.el | 84 +++++++++++++++++++++++++++++++++++
 1 file changed, 84 insertions(+)

diff --git a/testing/lisp/test-ox-ascii.el b/testing/lisp/test-ox-ascii.el
index fe12c0c27..07def1633 100644
--- a/testing/lisp/test-ox-ascii.el
+++ b/testing/lisp/test-ox-ascii.el
@@ -27,7 +27,91 @@ (require 'ox-ascii nil t)
 (unless (featurep 'ox-ascii)
   (signal 'missing-test-dependency "org-export-ascii"))
 
+(defun test-ox-ascii--restore-syntax ()
+  (org-link-make-regexps)
+  (when (featurep 'org-element) (org-element-update-syntax)))
+
+(defun test-ox-ascii--link-export-inline (path desc backend info)
+  (and (org-export-derived-backend-p backend 'ascii)
+       (let ((description (and (org-string-nw-p desc) (org-trim desc)))
+             (target (format "(|tststr:%s|)" path)))
+         (if description
+             (format "[|%s|] %s" description target)
+           target))))
 \f
+(ert-deftest test-ox-ascii/link-custom-protocol-fallback ()
+  "Test link custom protocol fallback."
+  (unwind-protect
+      (let ((org-link-parameters))
+        (org-link-set-parameters "tstdflt")
+        ;; As notes.
+        (let ((org-ascii-links-to-notes t))
+          (should ; With description.
+           (string-equal
+            (org-export-string-as
+             "Link [[tstdflt:path-descr][with description]] as note."
+             'ascii t)
+            "Link [with description] as note.
+\n
+[with description] <tstdflt:path-descr>\n"))
+          (should ; No description.
+           (string-equal
+            (org-export-string-as
+             "Link [[tstdflt:path-no-descr]] without description (note)."
+             'ascii t)
+            "Link <tstdflt:path-no-descr> without description (note).\n")))
+        ;; Inline.
+        (let ((org-ascii-links-to-notes nil))
+          (should ; With description.
+           (string-equal
+            (org-export-string-as
+             "Inline link [[tstdflt:path-descr][with description]]."
+             'ascii t)
+            "Inline link [with description] (<tstdflt:path-descr>).\n"))
+          (should ; No description.
+           (string-equal
+            (org-export-string-as
+             "Inline link [[tstdflt:path-no-descr]] without description."
+             'ascii t)
+            "Inline link <tstdflt:path-no-descr> without description.\n"))))
+    (test-ox-ascii--restore-syntax)))
+
+(ert-deftest test-ox-ascii/link-custom-protocol-string ()
+  "Test link custom protocol forced inline (string return value)."
+  (unwind-protect
+      (let ((org-link-parameters))
+        (org-link-set-parameters "tststr"
+                                 :export #'test-ox-ascii--link-export-inline)
+        ;; Inline despite as notes is requested.
+        (let ((org-ascii-links-to-notes t))
+          (should ; With description.
+           (string-equal
+            (org-export-string-as
+             "Link [[tststr:path-descr][with description]] as string (opt note)."
+             'ascii t)
+            "Link [|with description|] (|tststr:path-descr|) as string (opt note).\n"))
+          (should ; No description.
+           (string-equal
+            (org-export-string-as
+             "Link [[tststr:path-no-descr]] without description as string (opt note)."
+             'ascii t)
+            "Link (|tststr:path-no-descr|) without description as string (opt note).\n")))
+        ;; Inline.
+        (let ((org-ascii-links-to-notes nil))
+          (should ; With description.
+           (string-equal
+            (org-export-string-as
+             "Link [[tststr:path-descr][with description]] as string (opt inline)."
+             'ascii t)
+            "Link [|with description|] (|tststr:path-descr|) as string (opt inline).\n"))
+          (should ; No description.
+           (string-equal
+            (org-export-string-as
+             "Link <tststr:path-no-descr> without description as string (opt inline)."
+             'ascii t)
+            "Link (|tststr:path-no-descr|) without description as string (opt
+inline).\n"))))
+  (test-ox-ascii--restore-syntax)))
 
 (ert-deftest test-ox-ascii/list ()
   "Test lists."
-- 
2.39.2


[-- Attachment #3: 0002-ox-ascii.el-Refactor-link-export.patch --]
[-- Type: text/x-patch, Size: 4461 bytes --]

From d83861fb89de8882ec52144d8699e9cc7b11f947 Mon Sep 17 00:00:00 2001
From: Max Nikulin <manikulin@gmail.com>
Date: Fri, 20 Oct 2023 17:29:03 +0700
Subject: [PATCH 2/3] ox-ascii.el: Refactor link export

* lisp/ox-ascii.el (org-ascii--describe-links, org-ascii-link): Avoid
duplication of fragments of code.
(org-ascii-link-inline): A new helper function for `org-ascii-link'.

Prepare to expanding `org-link-parameters' :export protocol to allow
export of custom links as notes at the end of headings.
---
 lisp/ox-ascii.el | 66 ++++++++++++++++++++++++++++++------------------
 1 file changed, 41 insertions(+), 25 deletions(-)

diff --git a/lisp/ox-ascii.el b/lisp/ox-ascii.el
index 110bb4601..219e6efae 100644
--- a/lisp/ox-ascii.el
+++ b/lisp/ox-ascii.el
@@ -946,11 +946,13 @@ (defun org-ascii--describe-links (links width info)
    (lambda (link)
      (let* ((type (org-element-property :type link))
 	    (description (org-element-contents link))
+            (raw-link (org-element-property :raw-link link))
 	    (anchor (org-export-data
-		     (or description (org-element-property :raw-link link))
-		     info)))
+		     (or description raw-link)
+		     info))
+            location)
        (cond
-	((member type '("coderef" "radio")) nil)
+	((member type '("coderef" "radio")))
 	((member type '("custom-id" "fuzzy" "id"))
 	 ;; Only links with a description need an entry.  Other are
 	 ;; already handled in `org-ascii-link'.
@@ -963,25 +965,29 @@ (defun org-ascii--describe-links (links width info)
 			 (condition-case nil
                              (org-export-resolve-id-link link info)
                            (org-link-broken nil)))))
-             (when dest
-	       (concat
-	        (org-ascii--fill-string
-	         (format "[%s] %s" anchor (org-ascii--describe-datum dest info))
-	         width info)
-	        "\n\n")))))
+             (setq location
+                   (and dest (org-ascii--describe-datum dest info))))))
 	;; Do not add a link that cannot be resolved and doesn't have
 	;; any description: destination is already visible in the
 	;; paragraph.
-	((not (org-element-contents link)) nil)
+	((not description))
 	;; Do not add a link already handled by custom export
 	;; functions.
 	((org-export-custom-protocol-maybe link anchor 'ascii info) nil)
-	(t
-	 (concat
-	  (org-ascii--fill-string
-	   (format "[%s] <%s>" anchor (org-element-property :raw-link link))
-	   width info)
-	  "\n\n")))))
+	(t (setq location (format "<%s>" raw-link))))
+       (and
+        location
+        anchor
+	(concat
+	 (org-ascii--fill-string
+          (concat
+           (if (string-match-p "\\`\u200b*\\[.*\\]\u200b*\\'" anchor)
+               anchor
+	     (format "[%s]" anchor))
+           " "
+           location)
+	  width info)
+	  "\n\n"))))
    links ""))
 
 (defun org-ascii--checkbox (item info)
@@ -1584,6 +1590,17 @@ (defun org-ascii-line-break (_line-break _contents _info)
 
 ;;;; Link
 
+(defun org-ascii-link-inline (link desc info)
+  (cond
+   ((not (org-string-nw-p desc)) link)
+   ((plist-get info :ascii-links-to-notes)
+    (if (string-match-p "\\`\u200b*\\[.*\\]\u200b*\\'" desc)
+        desc
+      (format "[%s]" desc)))
+   ((string-match-p "\\`(.*)\\'" link)
+    (format "%s %s" desc link))
+   (t (format "%s (%s)" desc link))))
+
 (defun org-ascii-link (link desc info)
   "Transcode a LINK object from Org to ASCII.
 
@@ -1605,11 +1622,10 @@ (defun org-ascii-link (link desc info)
 			   (org-export-resolve-id-link link info))))
 	(pcase (org-element-type destination)
 	  ((guard desc)
-	   (if (plist-get info :ascii-links-to-notes)
-	       (format "[%s]" desc)
-	     (concat desc
-		     (format " (%s)"
-			     (org-ascii--describe-datum destination info)))))
+           (org-ascii-link-inline
+	    (org-ascii--describe-datum destination info)
+            desc
+            info))
 	  ;; External file.
 	  (`plain-text destination)
 	  (`headline
@@ -1628,10 +1644,10 @@ (defun org-ascii-link (link desc info)
 	  (_ "???"))))
      (t
       (let ((path (org-element-property :raw-link link)))
-	(if (not (org-string-nw-p desc)) (format "<%s>" path)
-	  (concat (format "[%s]" desc)
-		  (and (not (plist-get info :ascii-links-to-notes))
-		       (format " (<%s>)" path)))))))))
+        (org-ascii-link-inline
+         (format "<%s>" path)
+         (and (org-string-nw-p desc) (format "[%s]" desc))
+         info))))))
 
 
 ;;;; Node Properties
-- 
2.39.2


[-- Attachment #4: 0003-ox-ascii.el-Allow-to-export-custom-links-as-notes.patch --]
[-- Type: text/x-patch, Size: 7801 bytes --]

From bfd0625c9fb11bae29808714dc64d9cce03e7343 Mon Sep 17 00:00:00 2001
From: Max Nikulin <manikulin@gmail.com>
Date: Fri, 20 Oct 2023 23:35:16 +0700
Subject: [PATCH 3/3] ox-ascii.el: Allow to export custom links as notes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* lisp/ox-ascii.el (org-ascii--describe-links, org-ascii-link): Handle
(PATH . DESCRIPTION) values returned by :export property of
`org-link-parameters'.  It allows to respect `org-ascii-links-to-notes'
for custom link types.
* testing/lisp/test-ox-ascii.el
(test-ox-ascii/link-custom-protocol-cons): New test for the added
feature.
* lisp/ol-man.el (org-man-export): Allow to export links to man pages as
notes at the end of heading.

Actually I believe that proper export for man links is man(1), not a
URL to a web site, but I am not going to change it in this commit.

See the following mailing list thread:
Ihor Radchenko to emacs-orgmode… Re: Exporting elisp: and shell: links.
Sat, 14 Oct 2023 08:13:35 +0000.
https://list.orgmode.org/87wmvp1v0w.fsf@localhost
---
 lisp/ol-man.el                |  2 +-
 lisp/ox-ascii.el              | 29 +++++++++++--
 testing/lisp/test-ox-ascii.el | 79 +++++++++++++++++++++++++++++++++++
 3 files changed, 105 insertions(+), 5 deletions(-)

diff --git a/lisp/ol-man.el b/lisp/ol-man.el
index abe79086a..e0c56ed7b 100644
--- a/lisp/ol-man.el
+++ b/lisp/ol-man.el
@@ -91,7 +91,7 @@ (defun org-man-export (link description backend)
      ((eq backend 'html) (format "<a target=\"_blank\" href=\"%s\">%s</a>" path desc))
      ((eq backend 'latex) (format "\\href{%s}{%s}" path desc))
      ((eq backend 'texinfo) (format "@uref{%s,%s}" path desc))
-     ((eq backend 'ascii) (format "%s (%s)" desc path))
+     ((eq backend 'ascii) (cons path desc))
      ((eq backend 'md) (format "[%s](%s)" desc path))
      (t path))))
 
diff --git a/lisp/ox-ascii.el b/lisp/ox-ascii.el
index 219e6efae..b5407e934 100644
--- a/lisp/ox-ascii.el
+++ b/lisp/ox-ascii.el
@@ -967,13 +967,26 @@ (defun org-ascii--describe-links (links width info)
                            (org-link-broken nil)))))
              (setq location
                    (and dest (org-ascii--describe-datum dest info))))))
+	;; Do not add a link already handled by custom export
+	;; functions.
+	((pcase (org-export-custom-protocol-maybe
+                 link
+                 (and description (org-export-data description info))
+                 'ascii
+                 info)
+           ((pred null))
+           ((pred stringp) t)
+           (`(,(and (or `nil (pred stringp)) path) .
+              ,(and (or `nil (pred stringp)) desc))
+            (setq location (org-string-nw-p path))
+            (setq anchor desc)
+            t)
+           (_ (error "Link :export returned not cons, or string, or nil: %s"
+                     raw-link))))
 	;; Do not add a link that cannot be resolved and doesn't have
 	;; any description: destination is already visible in the
 	;; paragraph.
 	((not description))
-	;; Do not add a link already handled by custom export
-	;; functions.
-	((org-export-custom-protocol-maybe link anchor 'ascii info) nil)
 	(t (setq location (format "<%s>" raw-link))))
        (and
         location
@@ -1608,7 +1621,15 @@ (defun org-ascii-link (link desc info)
 INFO is a plist holding contextual information."
   (let ((type (org-element-property :type link)))
     (cond
-     ((org-export-custom-protocol-maybe link desc 'ascii info))
+     ((pcase (org-export-custom-protocol-maybe link desc 'ascii info)
+        ((pred null) nil) ; Use fallback.
+        ((and (pred stringp) str) str)
+        (`(nil . nil) "")
+        (`(,(and (or `nil (pred stringp)) custom-path) .
+           ,(and (or `nil (pred stringp)) custom-desc))
+         (org-ascii-link-inline custom-path custom-desc info))
+        (_ (error "Link :export returned not cons, or string, or nil: %s"
+                  (org-element-property :raw-link link)))))
      ((string= type "coderef")
       (let ((ref (org-element-property :path link)))
 	(format (org-export-get-coderef-format ref desc)
diff --git a/testing/lisp/test-ox-ascii.el b/testing/lisp/test-ox-ascii.el
index 07def1633..4afe8216f 100644
--- a/testing/lisp/test-ox-ascii.el
+++ b/testing/lisp/test-ox-ascii.el
@@ -113,6 +113,85 @@ (ert-deftest test-ox-ascii/link-custom-protocol-string ()
 inline).\n"))))
   (test-ox-ascii--restore-syntax)))
 
+(ert-deftest test-ox-ascii/link-custom-protocol-cons ()
+  "Test link custom protocol optional note (cons return value)."
+  (unwind-protect
+      (let ((org-link-parameters))
+        (org-link-set-parameters
+         "tstcons"
+         :export (lambda (path descr _backend _info)
+                   (cons (concat "excons-" path) descr)))
+        ;; As notes.
+        (let ((org-ascii-links-to-notes t))
+          (should ; With description.
+           (string-equal
+            (org-export-string-as
+             "Link [[tstcons:path-descr][with descr[iption]\u200b]] as note."
+             'ascii t)
+            "Link [with descr[iption]\u200b] as note.
+\n
+[with descr[iption]\u200b] excons-path-descr\n"))
+          (should ; No description.
+           (string-equal
+            (org-export-string-as
+             "Link <tstcons:path-no-descr> without description (note)."
+             'ascii t)
+            "Link excons-path-no-descr without description (note).\n")))
+        ;; Inline.
+        (let ((org-ascii-links-to-notes nil))
+          (should ; With description.
+           (string-equal
+            (org-export-string-as
+             "Inline link [[tstcons:path-descr][with description]]."
+             'ascii t)
+            "Inline link with description (excons-path-descr).\n"))
+          (should ; No description.
+           (string-equal
+            (org-export-string-as
+             "Inline link [[tstcons:path-no-descr]] without description."
+             'ascii t)
+            "Inline link excons-path-no-descr without description.\n")))
+        ;; Force parenthesis.
+        (let ((org-link-parameters))
+          (org-link-set-parameters
+           "brcons"
+           :export (lambda (path descr _backend _info)
+                     (cons (format "(exbr-%s)" path)
+                           (and descr (format "[%s]" descr)))))
+          (let ((org-ascii-links-to-notes t))
+            (should
+             (string-equal
+              (org-export-string-as
+               "Link [[brcons:path-descr][with brackets]] as note."
+               'ascii t)
+              "Link [with brackets] as note.
+\n
+[with brackets] (exbr-path-descr)\n")))
+          ;; Inline.
+          (let ((org-ascii-links-to-notes nil))
+            (should
+             (string-equal
+              (org-export-string-as
+               "Link [[brcons:path-descr][with brackets]] inline."
+               'ascii t)
+              "Link [with brackets] (exbr-path-descr) inline.\n"))))
+        ;; Error.
+        (org-link-set-parameters
+         "tsterr"
+         :export (lambda (path descr _backend _info)
+                   (list (concat "ex-error! " path) descr "extra arg")))
+        (let* ((err (should-error
+                     (org-export-string-as
+                      "Signals [[tsterr:invalid :export][aaa]] error."
+                      'ascii t)
+                     :type 'error))
+               (err-text (cadr err)))
+          (should-not (unless (and (stringp err-text)
+                                   (string-match-p "\\`Link :export returned not.*"
+                                                   err-text))
+                        err))))
+  (test-ox-ascii--restore-syntax)))
+
 (ert-deftest test-ox-ascii/list ()
   "Test lists."
   ;; Number counter.
-- 
2.39.2

Re: [RFC][PATCH] Allow to export to ascii custom link types as notes

[Ihor Radchenko]

Max Nikulin <manikulin@gmail.com> writes:

> it was discussed that attempts to customize export to plain text of link 
> types such as "elisp:" and "shell:" break formatting as notes at the end 
> of the heading (`org-ascii-links-to-notes').
>
> The attached patches is a draft implementing this feature (new functions 
> are not documented yet).
>
> For ascii backend :export function from `org-link-parameters' may return 
> (PATH . DESCRIPTION) `cons' instead of string. Depending on chosen link 
> style it will be exported as "[DESCRIPTION]" with the "[DESCRIPTION] 
> PATH" note at the end of heading or as the inline reference "DESCRIPTION 
> (PATH)".

This is non-standard. We should document it somewhere in the manual.

> I believe that parenthesis should be skipped in the case of angle 
> brackets "(<URI>)", but I do not change this behavior. There is some 
> inconsistency in respect to brackets for description of inline links, 
> but it is preserved as well.

May you elaborate?

> I do not like that :export functions are called twice: for text and for 
> note. In my opinion it is better to collect links in a property of INFO 
> to later format notes at the end of the heading. I would consider more 
> dense style of notes with list markers instead of empty line as separator.

Again, may you elaborate?

> +           (if (string-match-p "\\`\u200b*\\[.*\\]\u200b*\\'" anchor)
> +               anchor
> +	     (format "[%s]" anchor))

This is out of scope of the patch, isn't it?
I can see the motivation, but we should probably move this change to a
separate patch and discussion thread.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: [RFC][PATCH] Allow to export to ascii custom link types as notes

[Max Nikulin]

On 22/10/2023 16:13, Ihor Radchenko wrote:
> Max Nikulin writes:
> 
>> For ascii backend :export function from `org-link-parameters' may return
>> (PATH . DESCRIPTION) `cons' instead of string.
> 
> This is non-standard. We should document it somewhere in the manual.

Currently the question is whether it is acceptable or it should be 
changed to e.g. plist or even to use a callback.

>> I believe that parenthesis should be skipped in the case of angle
>> brackets "(<URI>)", but I do not change this behavior. There is some
>> inconsistency in respect to brackets for description of inline links,
>> but it is preserved as well.
> 
> May you elaborate?

I believe, parenthesis are not necessary when angle brackets are added 
around URI. Anyway currently behavior is not consistent and angle 
brackets are not added in some cases. I would prefer to stick to angle 
brackets and to drop parenthesis when <> are present.

>> I do not like that :export functions are called twice: for text and for
>> note. In my opinion it is better to collect links in a property of INFO
>> to later format notes at the end of the heading. I would consider more
>> dense style of notes with list markers instead of empty line as separator.
> 
> Again, may you elaborate?

List of links is added by `org-ascii--describe-links' that iterates over 
links earlier handled by `org-ascii-link', so :export function is called 
twice for each link having this property. I would consider collecting 
links in some property of the INFO argument instead. As a result 
`org-ascii--describe-link' would reuse results of formatters called by 
`org-ascii-link'.

Currently list of links is formatted as

[Description 1] <URL 1>

[Description 2] <URL 2>

 From my point of view it would not harm to have more dense formatting

- [Description 1] <URL 1>
- [Description 2] <URL 2>

>> +           (if (string-match-p "\\`\u200b*\\[.*\\]\u200b*\\'" anchor)
>> +               anchor
>> +	     (format "[%s]" anchor))
> 
> This is out of scope of the patch, isn't it?

Not really.

> I can see the motivation, but we should probably move this change to a
> separate patch and discussion thread.

In the case of inline links brackets are sometimes added around 
description, sometimes not. To keep current behavior I have decided that 
it is better to suppress duplicated brackets implicitly than to add an 
extra argument that controls adding [] explicitly. I do not insist on 
"\u200b*" that allows to handle duplication due to brackets in Org 
documents [[https://orgmode.org][\u200b[Org]\u200b]]. However I would 
prefer to keep the regexp for the case of brackets added by link formatters.

Re: [RFC][PATCH] Allow to export to ascii custom link types as notes

[Ihor Radchenko]

Max Nikulin <manikulin@gmail.com> writes:

>>> For ascii backend :export function from `org-link-parameters' may return
>>> (PATH . DESCRIPTION) `cons' instead of string.
>> 
>> This is non-standard. We should document it somewhere in the manual.
>
> Currently the question is whether it is acceptable or it should be 
> changed to e.g. plist or even to use a callback.

I see no problem with special return value of the link :export function.
In fact, I thought of similar approach globally, allowing :export
function to return AST data that will be further processed.

WRT cons vs. plist, I am mostly neutral. Slightly in favour of plist for
future extensibility.

I am not sure what you mean by callback.

>>> I believe that parenthesis should be skipped in the case of angle
>>> brackets "(<URI>)", but I do not change this behavior. There is some
>>> inconsistency in respect to brackets for description of inline links,
>>> but it is preserved as well.
>> 
>> May you elaborate?
>
> I believe, parenthesis are not necessary when angle brackets are added 
> around URI. Anyway currently behavior is not consistent and angle 
> brackets are not added in some cases. I would prefer to stick to angle 
> brackets and to drop parenthesis when <> are present.

May you provide an example when the angle brackets are not added?

>>> I do not like that :export functions are called twice: for text and for
>>> note. In my opinion it is better to collect links in a property of INFO
>>> to later format notes at the end of the heading. I would consider more
>>> dense style of notes with list markers instead of empty line as separator.
>> 
>> Again, may you elaborate?
>
> List of links is added by `org-ascii--describe-links' that iterates over 
> links earlier handled by `org-ascii-link', so :export function is called 
> twice for each link having this property. I would consider collecting 
> links in some property of the INFO argument instead. As a result 
> `org-ascii--describe-link' would reuse results of formatters called by 
> `org-ascii-link'.

It is already the case. `org-export-data' maintains export cache under
:exported-data hash table in INFO plist. So, the second call to
`org-export-data` will be cached.

> Currently list of links is formatted as
>
> [Description 1] <URL 1>
>
> [Description 2] <URL 2>
>
>  From my point of view it would not harm to have more dense formatting
>
> - [Description 1] <URL 1>
> - [Description 2] <URL 2>

I see no reason to change the existing behaviour here. Yes, I do not see
much harm, but changing the defaults is something we should only do when
there is a clear benefit. Harm may not always be anticipated by us in
advance.

>>> +           (if (string-match-p "\\`\u200b*\\[.*\\]\u200b*\\'" anchor)
>>> +               anchor
>>> +	     (format "[%s]" anchor))
>> 
>> This is out of scope of the patch, isn't it?
>
> Not really.

Do you mean "this is out of scope"?

>> I can see the motivation, but we should probably move this change to a
>> separate patch and discussion thread.
>
> In the case of inline links brackets are sometimes added around 
> description, sometimes not. To keep current behavior I have decided that 
> it is better to suppress duplicated brackets implicitly than to add an 
> extra argument that controls adding [] explicitly.

May you show an example?

> ... I do not insist on 
> "\u200b*" that allows to handle duplication due to brackets in Org 
> documents [[https://orgmode.org][\u200b[Org]\u200b]]. However I would 
> prefer to keep the regexp for the case of brackets added by link formatters.

I do not think that we need to handle zero-width spaces on backend
level. If we want to deal with them, it should be done globally, in
ox.el.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: [RFC][PATCH] Allow to export to ascii custom link types as notes

[Max Nikulin]

On 23/10/2023 16:17, Ihor Radchenko wrote:
> Max Nikulin writes:
> 
> WRT cons vs. plist, I am mostly neutral. Slightly in favour of plist for
> future extensibility.
> 
> I am not sure what you mean by callback.

Originally I had an idea that :export should call some function that 
adds a note to info. Now I have another proposal. Instead of returning a 
cons, :export function should return result of some new function, e.g. 
(org-ascii-make-link-with-note NOTE DESCRIPTION), so a `cons' or a plist 
becomes an implementation detail that may be changed any time. The only 
inconvenience is necessity to declare this function to allow lazy 
loading of ox-ascii and perhaps to avoid circular dependencies.

> May you provide an example when the angle brackets are not added?

angle and square brackets inconsistency

--- 8< ---
# (require 'ol-man)
# (setq org-ascii-links-to-notes nil)

- web :: [[http://orgmode.org][Org mode]]
- man :: [[man:man][man]]
- internal :: [[Heading][heading]]

* Heading
--- >8 ---
--- 8< ---
web
       [Org mode] (<http://orgmode.org>)
man
       man (http://man.he.net/?topic=man&section=all)
internal
       heading (See section 1)


1 Heading
═════════
--- >8 ---

>>>> +           (if (string-match-p "\\`\u200b*\\[.*\\]\u200b*\\'" anchor)
>>>> +               anchor
>>>> +	     (format "[%s]" anchor))
>>>
>>> This is out of scope of the patch, isn't it?
>>
>> Not really.
> 
> Do you mean "this is out of scope"?

I mean, it is a related change. E.g. ox-html and ox-latex do not add 
square brackets around link descriptions, it is specifics of ox-ascii. 
Square brackets are sometimes added for inline links, sometimes they are 
not. Square brackets are always added for links as notes. I would avoid 
duplicated square brackets when links are formatted as notes and for 
inline links when description is formatted with brackets.

Re: [RFC][PATCH] Allow to export to ascii custom link types as notes

[Ihor Radchenko]

Max Nikulin <manikulin@gmail.com> writes:

>> I am not sure what you mean by callback.
>
> Originally I had an idea that :export should call some function that 
> adds a note to info. Now I have another proposal. Instead of returning a 
> cons, :export function should return result of some new function, e.g. 
> (org-ascii-make-link-with-note NOTE DESCRIPTION), so a `cons' or a plist 
> becomes an implementation detail that may be changed any time.

Then, `org-ascii-make-link-with-note' may as well receive and modify
INFO plist. This way, ((org-export-custom-protocol-maybe link desc 'ascii info)) 
cond form will work without changes as `org-ascii-make-link-with-note`
will do all the necessary processing.

> ... The only 
> inconvenience is necessity to declare this function to allow lazy 
> loading of ox-ascii and perhaps to avoid circular dependencies.

This is not a problem.
If lazy loading is desired, one may simply use (require 'ox-ascii)
inside :export function to trigger loading when necessary.

>> May you provide an example when the angle brackets are not added?
>
> angle and square brackets inconsistency
>
> --- 8< ---
> # (require 'ol-man)
> # (setq org-ascii-links-to-notes nil)
>
> - web :: [[http://orgmode.org][Org mode]]
> - man :: [[man:man][man]]
> - internal :: [[Heading][heading]]
>
> * Heading
> --- >8 ---
> --- 8< ---
> web
>        [Org mode] (<http://orgmode.org>)
> man
>        man (http://man.he.net/?topic=man&section=all)

This is probably a bug in ol-man.

> internal
>        heading (See section 1)

I see no problem here - internal links are special, and it makes sense to
drop angle brackets, unlike external web links that are often marked
with angle brackets in the wild.

> 1 Heading
> ═════════
> --- >8 ---
>
>>>>> +           (if (string-match-p "\\`\u200b*\\[.*\\]\u200b*\\'" anchor)
>>>>> +               anchor
>>>>> +	     (format "[%s]" anchor))
>>>>
>>>> This is out of scope of the patch, isn't it?
>>>
>>> Not really.
>> 
>> Do you mean "this is out of scope"?
>
> I mean, it is a related change. E.g. ox-html and ox-latex do not add 
> square brackets around link descriptions, it is specifics of ox-ascii. 
> Square brackets are sometimes added for inline links, sometimes they are 
> not. Square brackets are always added for links as notes. I would avoid 
> duplicated square brackets when links are formatted as notes and for 
> inline links when description is formatted with brackets.

I did not mean unrelated to ox-ascii. I meant unrelated to "add new
feature allowing more flexibility for :export property of links when
exporting to ASCII".

I see handling anchors as a bugfix that should be discussed and
committed separately.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: [RFC][PATCH] Allow to export to ascii custom link types as notes

[Max Nikulin]

On 23/10/2023 19:09, Ihor Radchenko wrote:
> Max Nikulin writes:
> 
> Then, `org-ascii-make-link-with-note' may as well receive and modify
> INFO plist. This way, ((org-export-custom-protocol-maybe link desc 'ascii info))
> cond form will work without changes as `org-ascii-make-link-with-note`
> will do all the necessary processing.

Adding INFO argument is a bit more burden for users, but, I think, it is 
acceptable.

However "cond form will work without changes" is not clear for me. 
`org-export-custom-protocol-maybe' is called twice and depending on 
context the result should be either "[description]" inline or 
"[description] path" for note, so the code around 
`org-export-custom-protocol-maybe' has to be changed.

>> angle and square brackets inconsistency
>>
>> --- 8< ---
>> # (require 'ol-man)
>> # (setq org-ascii-links-to-notes nil)
>>
>> - web :: [[http://orgmode.org][Org mode]]
>> - man :: [[man:man][man]]
>> - internal :: [[Heading][heading]]
>>
>> * Heading
>> --- >8 ---
>> --- 8< ---
>> web
>>         [Org mode] (<http://orgmode.org>)
>> man
>>         man (http://man.he.net/?topic=man&section=all)
> 
> This is probably a bug in ol-man.

Which one? Absence of square brackets? Absence of angle brackets? Both?

>> internal
>>         heading (See section 1)
> 
> I see no problem here - internal links are special, and it makes sense to
> drop angle brackets, unlike external web links that are often marked
> with angle brackets in the wild.

Due to absence of square brackets around "heading" it should be treated 
differently from e.g. http links. It is the reason why I added a regexp 
to detect if a caller added square brackets:

>>>>>> +           (if (string-match-p "\\`\u200b*\\[.*\\]\u200b*\\'" anchor)
>>>>>> +               anchor
>>>>>> +	     (format "[%s]" anchor))

I do not like repetitions in the current code.

Re: [RFC][PATCH] Allow to export to ascii custom link types as notes

[Ihor Radchenko]

Max Nikulin <manikulin@gmail.com> writes:

> However "cond form will work without changes" is not clear for me. 
> `org-export-custom-protocol-maybe' is called twice and depending on 
> context the result should be either "[description]" inline or 
> "[description] path" for note, so the code around 
> `org-export-custom-protocol-maybe' has to be changed.

I see.
What about (1) passing link object to custom protocol, (2) making
`org-ascii-make-link-with-note' marking the link object to be recorded
in notes; (3) modifying `org-ascii--describe-links' to check for the
recorded mark before the `cond' clause (org-export-custom-protocol-maybe...).

>>>         [Org mode] (<http://orgmode.org>)
>>> man
>>>         man (http://man.he.net/?topic=man&section=all)
>> 
>> This is probably a bug in ol-man.
>
> Which one? Absence of square brackets? Absence of angle brackets? Both?

Should be [man] (<http://man.he.net/?topic=man&section=all>)

>>> internal
>>>         heading (See section 1)
>> 
>> I see no problem here - internal links are special, and it makes sense to
>> drop angle brackets, unlike external web links that are often marked
>> with angle brackets in the wild.
>
> Due to absence of square brackets around "heading" it should be treated 
> differently from e.g. http links.

Hmm.. I do see a problem now. To be consistent, it should be

[heading] (See section 1)

By "special" I meant URL/path part.

> ... It is the reason why I added a regexp 
> to detect if a caller added square brackets:
>
>>>>>>> +           (if (string-match-p "\\`\u200b*\\[.*\\]\u200b*\\'" anchor)
>>>>>>> +               anchor
>>>>>>> +	     (format "[%s]" anchor))

I still fail to see how it is related to the problem at hand: "Allow to
export to ascii custom link types as notes". We had this problem for
non-custom links in the past and we still have it. It should be solved
separately.

> I do not like repetitions in the current code.

Me either. But let's address them separately. Otherwise, it is very hard
to keep track of the discussion.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

[PATCH] ox-ascii.el: Consistently add brackets around links (was: Re: [RFC][PATCH] Allow to export to ascii custom link types as notes)

[Max Nikulin]

[-- Attachment #1: Type: text/plain, Size: 1243 bytes --]

On 24/10/2023 17:40, Ihor Radchenko wrote:
> Max Nikulin writes:
>>>>          [Org mode] (<http://orgmode.org>)
>>>> man
>>>>          man (http://man.he.net/?topic=man&section=all)
[...]
> Should be [man] (<http://man.he.net/?topic=man&section=all>)

Side note: it should be either just "man(1)" or "man(8)" without any URL 
for plain text export, but it is another story.

>>>> internal
>>>>          heading (See section 1)
[...]
> Hmm.. I do see a problem now. To be consistent, it should be
> 
> [heading] (See section 1)

See the attached patch.

After:

--- 8< ---
web
       [Org mode] (<http://orgmode.org>)
man
       [man] (<http://man.he.net/?topic=man&section=all>)
internal
       [heading] (See section 1)


1 Heading
═════════
--- >8 ---

Before:

--- 8< ---
web
       [Org mode] (<http://orgmode.org>)
man
       man (http://man.he.net/?topic=man&section=all)
internal
       heading (See section 1)


1 Heading
═════════
--- >8 ---

I would consider

--- 8< ---
web
       Org mode <http://orgmode.org>
man
       man <http://man.he.net/?topic=man&section=all>
internal
       heading (See section 1)


1 Heading
═════════
--- >8 ---

but inconsistency is worse anyway.

[-- Attachment #2: 0001-ox-ascii.el-Consistently-add-brackets-around-links.patch --]
[-- Type: text/x-patch, Size: 2812 bytes --]

From 3434fdf9b1669304ed2051c89554efc9922c5feb Mon Sep 17 00:00:00 2001
From: Max Nikulin <manikulin@gmail.com>
Date: Tue, 24 Oct 2023 21:45:36 +0700
Subject: [PATCH] ox-ascii.el: Consistently add brackets around links

* lisp/ox-ascii.el (org-ascii-link): Add square brackets around
description of fuzzy links when they are exported inline.
* lisp/ol-docview.el (org-docview-export):
* lisp/ox-ascii.el (org-ascii-link): Export links with square brackets
around description and angle brackets around path.

This make export of links inline (when `org-ascii-links-to-notes' is
nil) consistent with "http:" links: "[DESC] (<URI>)".

I would drop brackets for "http:" and similar links instead
("DESC (<URI>)" or even "DESC <URI>"), but any case I prefer
consistency.

Ihor Radchenko to emacs-orgmode. Re: [RFC][PATCH] Allow to export to
ascii custom link types as notes. Tue, 24 Oct 2023 10:40:41 +0000.
<https://list.orgmode.org/87edhk717a.fsf@localhost>
---
 lisp/ol-docview.el | 2 +-
 lisp/ol-man.el     | 2 +-
 lisp/ox-ascii.el   | 6 +++---
 3 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/lisp/ol-docview.el b/lisp/ol-docview.el
index bb9b34a17..bcb26520b 100644
--- a/lisp/ol-docview.el
+++ b/lisp/ol-docview.el
@@ -67,7 +67,7 @@ (defun org-docview-export (link description backend _info)
       (cond
        ((eq backend 'html) (format "<a href=\"%s\">%s</a>" path desc))
        ((eq backend 'latex) (format "\\href{%s}{%s}" path desc))
-       ((eq backend 'ascii) (format "%s (%s)" desc path))
+       ((eq backend 'ascii) (format "[%s] (<%s>)" desc path))
        (t path)))))
 
 (defun org-docview-open (link _)
diff --git a/lisp/ol-man.el b/lisp/ol-man.el
index abe79086a..645a6108e 100644
--- a/lisp/ol-man.el
+++ b/lisp/ol-man.el
@@ -91,7 +91,7 @@ (defun org-man-export (link description backend)
      ((eq backend 'html) (format "<a target=\"_blank\" href=\"%s\">%s</a>" path desc))
      ((eq backend 'latex) (format "\\href{%s}{%s}" path desc))
      ((eq backend 'texinfo) (format "@uref{%s,%s}" path desc))
-     ((eq backend 'ascii) (format "%s (%s)" desc path))
+     ((eq backend 'ascii) (format "[%s] (<%s>)" desc path))
      ((eq backend 'md) (format "[%s](%s)" desc path))
      (t path))))
 
diff --git a/lisp/ox-ascii.el b/lisp/ox-ascii.el
index 110bb4601..ae4273489 100644
--- a/lisp/ox-ascii.el
+++ b/lisp/ox-ascii.el
@@ -1607,9 +1607,9 @@ (defun org-ascii-link (link desc info)
 	  ((guard desc)
 	   (if (plist-get info :ascii-links-to-notes)
 	       (format "[%s]" desc)
-	     (concat desc
-		     (format " (%s)"
-			     (org-ascii--describe-datum destination info)))))
+	     (format "[%s] (%s)"
+                     desc
+		     (org-ascii--describe-datum destination info))))
 	  ;; External file.
 	  (`plain-text destination)
 	  (`headline
-- 
2.39.2

Re: [PATCH] ox-ascii.el: Consistently add brackets around links (was: Re: [RFC][PATCH] Allow to export to ascii custom link types as notes)

[Ihor Radchenko]

Max Nikulin <manikulin@gmail.com> writes:

>> Should be [man] (<http://man.he.net/?topic=man&section=all>)
>
> Side note: it should be either just "man(1)" or "man(8)" without any URL 
> for plain text export, but it is another story.

I would not say "should". May? Yes. URL also makes sense in some
scenarios (when the intended reader is not on Linux).

> From 3434fdf9b1669304ed2051c89554efc9922c5feb Mon Sep 17 00:00:00 2001
> From: Max Nikulin <manikulin@gmail.com>
> Date: Tue, 24 Oct 2023 21:45:36 +0700
> Subject: [PATCH] ox-ascii.el: Consistently add brackets around links

Applied, onto main.
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=9cbaf8e49

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

[RFC][PATCH v2] Allow to export to ascii custom link types as notes

[Max Nikulin]

[-- Attachment #1: Type: text/plain, Size: 813 bytes --]

On 23/10/2023 19:09, Ihor Radchenko wrote:
>>>>>> +           (if (string-match-p "\\`\u200b*\\[.*\\]\u200b*\\'" anchor)
>>>>>> +               anchor
>>>>>> +	     (format "[%s]" anchor))
> 
> I did not mean unrelated to ox-ascii. I meant unrelated to "add new
> feature allowing more flexibility for :export property of links when
> exporting to ASCII".

Since "ox-ascii.el: Consistently add brackets around links" has been 
committed, this regexp is not necessary to preserve inconsistencies in 
link formatting. Avoiding duplication of brackets was just a bonus.

See next version of the draft. Functions are still not documented.

`cons' is made an implementation detail, however completely opaque 
structure is an obstacle for derived export backend. Perhaps getter 
functions should be introduced as well.

[-- Attachment #2: 0001-test-ox-ascii.el-Test-custom-links.patch --]
[-- Type: text/x-patch, Size: 4747 bytes --]

From f6891e33522c1ec321d01d8c3986fbf789c79224 Mon Sep 17 00:00:00 2001
From: Max Nikulin <manikulin@gmail.com>
Date: Fri, 20 Oct 2023 17:10:36 +0700
Subject: [PATCH 1/3] test-ox-ascii.el: Test custom links

* testing/lisp/test-ox-ascii.el (test-ox-ascii--restore-syntax)
(test-ox-ascii--link-export-inline): Helper functions.
(test-ox-ascii/link-custom-protocol-fallback)
(test-ox-ascii/link-custom-protocol-string): Test export of custom link
types having the :export parameters or relying on format provided by
default when `org-ascii-links-to-notes' enabled or disabled.
---
 testing/lisp/test-ox-ascii.el | 84 +++++++++++++++++++++++++++++++++++
 1 file changed, 84 insertions(+)

diff --git a/testing/lisp/test-ox-ascii.el b/testing/lisp/test-ox-ascii.el
index fe12c0c27..07def1633 100644
--- a/testing/lisp/test-ox-ascii.el
+++ b/testing/lisp/test-ox-ascii.el
@@ -27,7 +27,91 @@ (require 'ox-ascii nil t)
 (unless (featurep 'ox-ascii)
   (signal 'missing-test-dependency "org-export-ascii"))
 
+(defun test-ox-ascii--restore-syntax ()
+  (org-link-make-regexps)
+  (when (featurep 'org-element) (org-element-update-syntax)))
+
+(defun test-ox-ascii--link-export-inline (path desc backend info)
+  (and (org-export-derived-backend-p backend 'ascii)
+       (let ((description (and (org-string-nw-p desc) (org-trim desc)))
+             (target (format "(|tststr:%s|)" path)))
+         (if description
+             (format "[|%s|] %s" description target)
+           target))))
 \f
+(ert-deftest test-ox-ascii/link-custom-protocol-fallback ()
+  "Test link custom protocol fallback."
+  (unwind-protect
+      (let ((org-link-parameters))
+        (org-link-set-parameters "tstdflt")
+        ;; As notes.
+        (let ((org-ascii-links-to-notes t))
+          (should ; With description.
+           (string-equal
+            (org-export-string-as
+             "Link [[tstdflt:path-descr][with description]] as note."
+             'ascii t)
+            "Link [with description] as note.
+\n
+[with description] <tstdflt:path-descr>\n"))
+          (should ; No description.
+           (string-equal
+            (org-export-string-as
+             "Link [[tstdflt:path-no-descr]] without description (note)."
+             'ascii t)
+            "Link <tstdflt:path-no-descr> without description (note).\n")))
+        ;; Inline.
+        (let ((org-ascii-links-to-notes nil))
+          (should ; With description.
+           (string-equal
+            (org-export-string-as
+             "Inline link [[tstdflt:path-descr][with description]]."
+             'ascii t)
+            "Inline link [with description] (<tstdflt:path-descr>).\n"))
+          (should ; No description.
+           (string-equal
+            (org-export-string-as
+             "Inline link [[tstdflt:path-no-descr]] without description."
+             'ascii t)
+            "Inline link <tstdflt:path-no-descr> without description.\n"))))
+    (test-ox-ascii--restore-syntax)))
+
+(ert-deftest test-ox-ascii/link-custom-protocol-string ()
+  "Test link custom protocol forced inline (string return value)."
+  (unwind-protect
+      (let ((org-link-parameters))
+        (org-link-set-parameters "tststr"
+                                 :export #'test-ox-ascii--link-export-inline)
+        ;; Inline despite as notes is requested.
+        (let ((org-ascii-links-to-notes t))
+          (should ; With description.
+           (string-equal
+            (org-export-string-as
+             "Link [[tststr:path-descr][with description]] as string (opt note)."
+             'ascii t)
+            "Link [|with description|] (|tststr:path-descr|) as string (opt note).\n"))
+          (should ; No description.
+           (string-equal
+            (org-export-string-as
+             "Link [[tststr:path-no-descr]] without description as string (opt note)."
+             'ascii t)
+            "Link (|tststr:path-no-descr|) without description as string (opt note).\n")))
+        ;; Inline.
+        (let ((org-ascii-links-to-notes nil))
+          (should ; With description.
+           (string-equal
+            (org-export-string-as
+             "Link [[tststr:path-descr][with description]] as string (opt inline)."
+             'ascii t)
+            "Link [|with description|] (|tststr:path-descr|) as string (opt inline).\n"))
+          (should ; No description.
+           (string-equal
+            (org-export-string-as
+             "Link <tststr:path-no-descr> without description as string (opt inline)."
+             'ascii t)
+            "Link (|tststr:path-no-descr|) without description as string (opt
+inline).\n"))))
+  (test-ox-ascii--restore-syntax)))
 
 (ert-deftest test-ox-ascii/list ()
   "Test lists."
-- 
2.39.2


[-- Attachment #3: 0002-ox-ascii.el-Refactor-link-export.patch --]
[-- Type: text/x-patch, Size: 4157 bytes --]

From fd6d686bb9e09981d05cbfc0ddab74dc8bcceb99 Mon Sep 17 00:00:00 2001
From: Max Nikulin <manikulin@gmail.com>
Date: Fri, 20 Oct 2023 17:29:03 +0700
Subject: [PATCH 2/3] ox-ascii.el: Refactor link export

* lisp/ox-ascii.el (org-ascii--describe-links, org-ascii-link): Avoid
duplication of fragments of code.
(org-ascii-link-inline): A new helper function for `org-ascii-link'.

Prepare to expanding `org-link-parameters' :export protocol to allow
export of custom links as notes at the end of headings.
---
 lisp/ox-ascii.el | 56 +++++++++++++++++++++++++++---------------------
 1 file changed, 31 insertions(+), 25 deletions(-)

diff --git a/lisp/ox-ascii.el b/lisp/ox-ascii.el
index ae4273489..10bb1fce7 100644
--- a/lisp/ox-ascii.el
+++ b/lisp/ox-ascii.el
@@ -946,11 +946,13 @@ (defun org-ascii--describe-links (links width info)
    (lambda (link)
      (let* ((type (org-element-property :type link))
 	    (description (org-element-contents link))
+            (raw-link (org-element-property :raw-link link))
 	    (anchor (org-export-data
-		     (or description (org-element-property :raw-link link))
-		     info)))
+		     (or description raw-link)
+		     info))
+            location)
        (cond
-	((member type '("coderef" "radio")) nil)
+	((member type '("coderef" "radio")))
 	((member type '("custom-id" "fuzzy" "id"))
 	 ;; Only links with a description need an entry.  Other are
 	 ;; already handled in `org-ascii-link'.
@@ -963,25 +965,24 @@ (defun org-ascii--describe-links (links width info)
 			 (condition-case nil
                              (org-export-resolve-id-link link info)
                            (org-link-broken nil)))))
-             (when dest
-	       (concat
-	        (org-ascii--fill-string
-	         (format "[%s] %s" anchor (org-ascii--describe-datum dest info))
-	         width info)
-	        "\n\n")))))
+             (setq location
+                   (and dest (org-ascii--describe-datum dest info))))))
 	;; Do not add a link that cannot be resolved and doesn't have
 	;; any description: destination is already visible in the
 	;; paragraph.
-	((not (org-element-contents link)) nil)
+	((not description))
 	;; Do not add a link already handled by custom export
 	;; functions.
 	((org-export-custom-protocol-maybe link anchor 'ascii info) nil)
-	(t
-	 (concat
-	  (org-ascii--fill-string
-	   (format "[%s] <%s>" anchor (org-element-property :raw-link link))
-	   width info)
-	  "\n\n")))))
+	(t (setq location (format "<%s>" raw-link))))
+       (and
+        location
+        anchor
+	(concat
+	 (org-ascii--fill-string
+	  (format "[%s] %s" anchor location)
+	  width info)
+	  "\n\n"))))
    links ""))
 
 (defun org-ascii--checkbox (item info)
@@ -1584,6 +1585,15 @@ (defun org-ascii-line-break (_line-break _contents _info)
 
 ;;;; Link
 
+(defun org-ascii-link-inline (link desc info)
+  (cond
+   ((not desc) link)
+   ((plist-get info :ascii-links-to-notes)
+    (format "[%s]" desc))
+   ((string-match-p "\\`(.*)\\'" link)
+    (format "[%s] %s" desc link))
+   (t (format "[%s] (%s)" desc link))))
+
 (defun org-ascii-link (link desc info)
   "Transcode a LINK object from Org to ASCII.
 
@@ -1605,11 +1615,10 @@ (defun org-ascii-link (link desc info)
 			   (org-export-resolve-id-link link info))))
 	(pcase (org-element-type destination)
 	  ((guard desc)
-	   (if (plist-get info :ascii-links-to-notes)
-	       (format "[%s]" desc)
-	     (format "[%s] (%s)"
-                     desc
-		     (org-ascii--describe-datum destination info))))
+           (org-ascii-link-inline
+	    (org-ascii--describe-datum destination info)
+            desc
+            info))
 	  ;; External file.
 	  (`plain-text destination)
 	  (`headline
@@ -1628,10 +1637,7 @@ (defun org-ascii-link (link desc info)
 	  (_ "???"))))
      (t
       (let ((path (org-element-property :raw-link link)))
-	(if (not (org-string-nw-p desc)) (format "<%s>" path)
-	  (concat (format "[%s]" desc)
-		  (and (not (plist-get info :ascii-links-to-notes))
-		       (format " (<%s>)" path)))))))))
+        (org-ascii-link-inline (format "<%s>" path) desc info))))))
 
 
 ;;;; Node Properties
-- 
2.39.2


[-- Attachment #4: 0003-ox-ascii.el-Allow-to-export-custom-links-as-notes.patch --]
[-- Type: text/x-patch, Size: 10553 bytes --]

From dfde96e6b31da8cb9a25c98434237da4f78272f5 Mon Sep 17 00:00:00 2001
From: Max Nikulin <manikulin@gmail.com>
Date: Fri, 20 Oct 2023 23:35:16 +0700
Subject: [PATCH 3/3] ox-ascii.el: Allow to export custom links as notes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* lisp/ox-ascii.el (org-ascii-make-link-formatted): New function whose
value may be returned by the :export property of `org-link-parameters'
to create links optionally formatted similar to footnotes.
(org-ascii--describe-links, org-ascii-link): Handle values returned by
`org-ascii-make-link-formatted'.  It allows to respect
`org-ascii-links-to-notes' for custom link types.
* testing/lisp/test-ox-ascii.el
(test-ox-ascii/link-custom-protocol-cons): New test for the added
feature.
* lisp/ol-man.el (org-man-export):
* lisp/ol-docview.el (org-docview-export): Allow to export links to man
pages and to documents as notes at the end of heading.

See the following mailing list thread:
Ihor Radchenko to emacs-orgmode… Re: Exporting elisp: and shell: links.
Sat, 14 Oct 2023 08:13:35 +0000.
https://list.orgmode.org/87wmvp1v0w.fsf@localhost
---
 lisp/ol-docview.el            |  6 ++-
 lisp/ol-man.el                |  6 ++-
 lisp/ox-ascii.el              | 34 ++++++++++++--
 testing/lisp/test-ox-ascii.el | 83 +++++++++++++++++++++++++++++++++++
 4 files changed, 121 insertions(+), 8 deletions(-)

diff --git a/lisp/ol-docview.el b/lisp/ol-docview.el
index bcb26520b..fd945fe2e 100644
--- a/lisp/ol-docview.el
+++ b/lisp/ol-docview.el
@@ -51,13 +51,14 @@ (require 'ol)
 (declare-function doc-view-goto-page "doc-view" (page))
 (declare-function image-mode-window-get "image-mode" (prop &optional winprops))
 (declare-function org-open-file "org" (path &optional in-emacs line search))
+(declare-function org-ascii-make-link-formatted "ox-ascii" (path desc info))
 
 (org-link-set-parameters "docview"
 			 :follow #'org-docview-open
 			 :export #'org-docview-export
 			 :store #'org-docview-store-link)
 
-(defun org-docview-export (link description backend _info)
+(defun org-docview-export (link description backend info)
   "Export a docview LINK with DESCRIPTION for BACKEND."
   (let ((path (if (string-match "\\(.+\\)::.+" link) (match-string 1 link)
 		link))
@@ -67,7 +68,8 @@ (defun org-docview-export (link description backend _info)
       (cond
        ((eq backend 'html) (format "<a href=\"%s\">%s</a>" path desc))
        ((eq backend 'latex) (format "\\href{%s}{%s}" path desc))
-       ((eq backend 'ascii) (format "[%s] (<%s>)" desc path))
+       ((eq backend 'ascii)
+        (org-ascii-make-link-formatted (format "(<%s>)" path) desc info))
        (t path)))))
 
 (defun org-docview-open (link _)
diff --git a/lisp/ol-man.el b/lisp/ol-man.el
index b0701c689..da1cca9ed 100644
--- a/lisp/ol-man.el
+++ b/lisp/ol-man.el
@@ -33,6 +33,8 @@ (org-assert-version)
 
 (require 'ol)
 
+(declare-function org-ascii-make-link-formatted "ox-ascii" (path desc info))
+
 (org-link-set-parameters "man"
 			 :follow #'org-man-open
 			 :export #'org-man-export
@@ -86,7 +88,7 @@ (defun org-man-get-page-name ()
       (match-string 1 (buffer-name))
     (error "Cannot create link to this man page")))
 
-(defun org-man-export (link description backend)
+(defun org-man-export (link description backend info)
   "Export a man page LINK with DESCRIPTION.
 BACKEND is the current export backend."
   (let ((path (format "http://man.he.net/?topic=%s&section=all" link))
@@ -95,7 +97,7 @@ (defun org-man-export (link description backend)
      ((eq backend 'html) (format "<a target=\"_blank\" href=\"%s\">%s</a>" path desc))
      ((eq backend 'latex) (format "\\href{%s}{%s}" path desc))
      ((eq backend 'texinfo) (format "@uref{%s,%s}" path desc))
-     ((eq backend 'ascii) (format "[%s] (<%s>)" desc path))
+     ((eq backend 'ascii) (org-ascii-make-link-formatted (format "<%s>" path) desc info))
      ((eq backend 'md) (format "[%s](%s)" desc path))
      (t path))))
 
diff --git a/lisp/ox-ascii.el b/lisp/ox-ascii.el
index 10bb1fce7..722b2aa4c 100644
--- a/lisp/ox-ascii.el
+++ b/lisp/ox-ascii.el
@@ -967,13 +967,26 @@ (defun org-ascii--describe-links (links width info)
                            (org-link-broken nil)))))
              (setq location
                    (and dest (org-ascii--describe-datum dest info))))))
+	;; Do not add a link already handled by custom export
+	;; functions.
+	((pcase (org-export-custom-protocol-maybe
+                 link
+                 (and description (org-export-data description info))
+                 'ascii
+                 info)
+           ((pred null))
+           ((pred stringp) t)
+           (`(,(and (or `nil (pred stringp)) path) .
+              ,(and (or `nil (pred stringp)) desc))
+            (setq location (org-string-nw-p path))
+            (setq anchor desc)
+            t)
+           (_ (error "Link :export returned not cons, or string, or nil: %s"
+                     raw-link))))
 	;; Do not add a link that cannot be resolved and doesn't have
 	;; any description: destination is already visible in the
 	;; paragraph.
 	((not description))
-	;; Do not add a link already handled by custom export
-	;; functions.
-	((org-export-custom-protocol-maybe link anchor 'ascii info) nil)
 	(t (setq location (format "<%s>" raw-link))))
        (and
         location
@@ -1601,7 +1614,15 @@ (defun org-ascii-link (link desc info)
 INFO is a plist holding contextual information."
   (let ((type (org-element-property :type link)))
     (cond
-     ((org-export-custom-protocol-maybe link desc 'ascii info))
+     ((pcase (org-export-custom-protocol-maybe link desc 'ascii info)
+        ((pred null) nil) ; Use fallback.
+        ((and (pred stringp) str) str)
+        (`(nil . nil) "")
+        (`(,(and (or `nil (pred stringp)) custom-path) .
+           ,(and (or `nil (pred stringp)) custom-desc))
+         (org-ascii-link-inline custom-path custom-desc info))
+        (_ (error "Link :export returned not cons, or string, or nil: %s"
+                  (org-element-property :raw-link link)))))
      ((string= type "coderef")
       (let ((ref (org-element-property :path link)))
 	(format (org-export-get-coderef-format ref desc)
@@ -2224,6 +2245,11 @@ (defun org-ascii-publish-to-utf8 (plist filename pub-dir)
   (org-publish-org-to
    'ascii filename ".txt" `(:ascii-charset utf-8 ,@plist) pub-dir))
 
+(defun org-ascii-make-link-formatted (path descr _info)
+  "To be used in :export property of `org-link-parameters'.
+Returns an opaque type interpreted by `org-ascii-link'."
+  (cons path descr))
+
 
 (provide 'ox-ascii)
 
diff --git a/testing/lisp/test-ox-ascii.el b/testing/lisp/test-ox-ascii.el
index 07def1633..5165e867c 100644
--- a/testing/lisp/test-ox-ascii.el
+++ b/testing/lisp/test-ox-ascii.el
@@ -113,6 +113,89 @@ (ert-deftest test-ox-ascii/link-custom-protocol-string ()
 inline).\n"))))
   (test-ox-ascii--restore-syntax)))
 
+(ert-deftest test-ox-ascii/link-custom-protocol-cons ()
+  "Test of custom link type optionally exported as a note."
+  (unwind-protect
+      (let ((org-link-parameters))
+        (org-link-set-parameters
+         "tstcons"
+         :export (lambda (path descr _backend info)
+                   (org-ascii-make-link-formatted
+                    (concat "excons-" path) descr info)))
+        ;; As notes.
+        (let ((org-ascii-links-to-notes t))
+          (should ; With description.
+           (string-equal
+            (org-export-string-as
+             "Link [[tstcons:path-descr][with descr[iption]\u200b]] as note."
+             'ascii t)
+            "Link [with descr[iption]\u200b] as note.
+\n
+[with descr[iption]\u200b] excons-path-descr\n"))
+          (should ; No description.
+           (string-equal
+            (org-export-string-as
+             "Link <tstcons:path-no-descr> without description (note)."
+             'ascii t)
+            "Link excons-path-no-descr without description (note).\n")))
+        ;; Inline.
+        (let ((org-ascii-links-to-notes nil))
+          (should ; With description.
+           (string-equal
+            (org-export-string-as
+             "Inline link [[tstcons:path-descr][with description]]."
+             'ascii t)
+            "Inline link [with description] (excons-path-descr).\n"))
+          (should ; No description.
+           (string-equal
+            (org-export-string-as
+             "Inline link [[tstcons:path-no-descr]] without description."
+             'ascii t)
+            "Inline link excons-path-no-descr without description.\n")))
+        ;; Ugly formatting with duplicated brackets.
+        ;; Behavior likely should be changed to not add another pair of brackets.
+        (let ((org-link-parameters))
+          (org-link-set-parameters
+           "brcons"
+           :export (lambda (path descr _backend info)
+                     (org-ascii-make-link-formatted
+                      (format "(exbr-%s)" path)
+                      (and descr (format "[%s]" descr))
+                      info)))
+          (let ((org-ascii-links-to-notes t))
+            (should
+             (string-equal
+              (org-export-string-as
+               "Link [[brcons:path-descr][with brackets]] as note."
+               'ascii t)
+              "Link [[with brackets]] as note.
+\n
+[[with brackets]] (exbr-path-descr)\n")))
+          ;; Inline.
+          (let ((org-ascii-links-to-notes nil))
+            (should
+             (string-equal
+              (org-export-string-as
+               "Link [[brcons:path-descr][with brackets]] inline."
+               'ascii t)
+              "Link [[with brackets]] (exbr-path-descr) inline.\n"))))
+        ;; Error.
+        (org-link-set-parameters
+         "tsterr"
+         :export (lambda (path descr _backend _info)
+                   (list (concat "ex-error! " path) descr "extra arg")))
+        (let* ((err (should-error
+                     (org-export-string-as
+                      "Signals [[tsterr:invalid :export][aaa]] error."
+                      'ascii t)
+                     :type 'error))
+               (err-text (cadr err)))
+          (should-not (unless (and (stringp err-text)
+                                   (string-match-p "\\`Link :export returned not.*"
+                                                   err-text))
+                        err))))
+  (test-ox-ascii--restore-syntax)))
+
 (ert-deftest test-ox-ascii/list ()
   "Test lists."
   ;; Number counter.
-- 
2.39.2

man pages references (Re: [PATCH] ox-ascii.el: Consistently add brackets around links)

[Max Nikulin]

On 25/10/2023 17:34, Ihor Radchenko wrote:
> Max Nikulin writes:
> 
>>> Should be [man] (<http://man.he.net/?topic=man&section=all>)
>>
>> Side note: it should be either just "man(1)" or "man(8)" without any URL
>> for plain text export, but it is another story.
> 
> I would not say "should". May? Yes. URL also makes sense in some
> scenarios (when the intended reader is not on Linux).

URL makes sense when it is particular version or a page generated 
without intermediate roff format, but this case it is https:, not man: 
link. Compare (sorry, man.he.net is terribly obsolete)
http://storaged.org/doc/udisks2-api/latest/udisks.8.html#id-1.2.4.7
that has more links than the page generated from man page (debiman still 
recognizes much more cross-references than emacs man buffers)
https://manpages.debian.org/bookworm/udisks2/udisks.8.en.html#DEVICE_INFORMATION

"man(1)" references were used in paper documents when internet was not 
always available. In books references may be emphasized by italics or 
fixed width font.

I like formatting similar to "systemd-resolved(8) § /ETC/RESOLV.CONF"
https://wiki.archlinux.org/title/Systemd-resolved
It makes clear that links point to man pages and precise enough since 
specific sections are provided.

Re: [RFC][PATCH] Allow to export to ascii custom link types as notes

[Max Nikulin]

On 24/10/2023 17:40, Ihor Radchenko wrote:
> What about (1) passing link object to custom protocol,

You know, I like this idea, but a function receiving link org-element 
object should be set to another property, so :export should continue to 
work.

You considered :filter. I would prefer something related to "export", 
but I can not suggest a better name.

Ihor Radchenko. Re: [BUG] URI handling is overly complicated and 
nonstandard [9.6.7 (N/A @ 
/gnu/store/mg7223g8mw90lccp6mm5g6f3mpjk70si-emacs-org-9.6.7/share/emacs/site-lisp/org-9.6.7/)] 
Tue, 05 Sep 2023 09:42:23 +0000.
https://list.orgmode.org/8734ztvtvk.fsf@localhost

Re: man pages references (Re: [PATCH] ox-ascii.el: Consistently add brackets around links)

[Ihor Radchenko]

Max Nikulin <manikulin@gmail.com> writes:

>>> Side note: it should be either just "man(1)" or "man(8)" without any URL
>>> for plain text export, but it is another story.
>> 
>> I would not say "should". May? Yes. URL also makes sense in some
>> scenarios (when the intended reader is not on Linux).
>
> URL makes sense when it is particular version or a page generated 
> without intermediate roff format, but this case it is https:, not man: 
> link. Compare (sorry, man.he.net is terribly obsolete)
> http://storaged.org/doc/udisks2-api/latest/udisks.8.html#id-1.2.4.7
> that has more links than the page generated from man page (debiman still 
> recognizes much more cross-references than emacs man buffers)
> https://manpages.debian.org/bookworm/udisks2/udisks.8.en.html#DEVICE_INFORMATION

I do not see why man.he.net is obsolete - it does not look like it is
unmaintained. That said, feel free to submit a patch with online man
pages website being customizeable.

> "man(1)" references were used in paper documents when internet was not 
> always available. In books references may be emphasized by italics or 
> fixed width font.
>
> I like formatting similar to "systemd-resolved(8) § /ETC/RESOLV.CONF"
> https://wiki.archlinux.org/title/Systemd-resolved
> It makes clear that links point to man pages and precise enough since 
> specific sections are provided.

I have no objections about having this export style as a user option.
Again, patches welcome.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: [RFC][PATCH v2] Allow to export to ascii custom link types as notes

[Ihor Radchenko]

Max Nikulin <manikulin@gmail.com> writes:

> `cons' is made an implementation detail, however completely opaque 
> structure is an obstacle for derived export backend. Perhaps getter 
> functions should be introduced as well.

I am looking at this again and the approach with special return values
really feels like a kludge.

What about passing an extra argument to :export function in
`org-export-custom-protocol-maybe':

(funcall protocol path desc backend info *link-object*)

Then, if the :export function returns non-string, the return value is
further processed as (org-export-data *return-value* info).

This way, we can transparently return an https link in ol-man's
`org-man-export' that will be handled automatically taking into account
the ASCII inline note settings.

All the existing export backends will continue working without
modification.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: [RFC][PATCH v2] Allow to export to ascii custom link types as notes

[Max Nikulin]

On 07/11/2023 16:30, Ihor Radchenko wrote:
> Max Nikulin writes:
> 
> What about passing an extra argument to :export function in
> `org-export-custom-protocol-maybe':
> 
> (funcall protocol path desc backend info *link-object*)

It would require another iteration with `condition-case' to deal with 
functions having old signature.

Earlier you considered :filter property that receives link object 
instead of path and desc pair. I am unsure concerning name, but I like 
that idea.

> Then, if the :export function returns non-string, the return value is
> further processed as (org-export-data *return-value* info).

Do you mean something like the following?

(defun org-man-export (link description backend)
   "Export a man page LINK with DESCRIPTION.
BACKEND is the current export backend."
   (org-element-create-link
    (format "http://man.he.net/?topic=%s&section=all" link)
    description))

where org-element-create-link parses link target into :type, :raw-link, 
etc. properties.

Re: [RFC][PATCH v2] Allow to export to ascii custom link types as notes

[Ihor Radchenko]

Max Nikulin <manikulin@gmail.com> writes:

>> What about passing an extra argument to :export function in
>> `org-export-custom-protocol-maybe':
>> 
>> (funcall protocol path desc backend info *link-object*)
>
> It would require another iteration with `condition-case' to deal with 
> functions having old signature.

Is it a problem?
We can alternatively check function arity.

> Earlier you considered :filter property that receives link object 
> instead of path and desc pair. I am unsure concerning name, but I like 
> that idea.

I feel that :filter + :export will be rather redundant - they will do
the same thing and only differ by calling convention. And we will have
issues with priority of :filter vs. :export if both happen to be
present (e.g. when a user defines a custom :export in personal config).

I guess we may instead make :filter apply earlier, right after
`org-export-filter-parse-tree-functions'. Then, it will be called before
export transcoding process begins.

>> Then, if the :export function returns non-string, the return value is
>> further processed as (org-export-data *return-value* info).
>
> Do you mean something like the following?
>
> (defun org-man-export (link description backend)
>    "Export a man page LINK with DESCRIPTION.
> BACKEND is the current export backend."
>    (org-element-create-link
>     (format "http://man.he.net/?topic=%s&section=all" link)
>     description))
>
> where org-element-create-link parses link target into :type, :raw-link, 
> etc. properties.

Yes.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: [RFC][PATCH v2] Allow to export to ascii custom link types as notes

[Max Nikulin]

On 07/11/2023 18:58, Ihor Radchenko wrote:
> Max Nikulin writes:
> 
>>> (funcall protocol path desc backend info *link-object*)
>>
>> It would require another iteration with `condition-case' to deal with
>> functions having old signature.
> 
> Is it a problem?

Performance for large projects like Worg.

> We can alternatively check function arity.

5 unnamed arguments for functions that are supposed to be implemented by 
users looks rather close to a border when it becomes fragile. The 
language does not enforce type checking for user-supplied functions and 
users would not bother as well. Multi-argument functions was a painful 
experience with FORTRAN for me (fortunately I was not deeply involved).

>> Earlier you considered :filter property that receives link object
>> instead of path and desc pair. I am unsure concerning name, but I like
>> that idea.
> 
> I feel that :filter + :export will be rather redundant - they will do
> the same thing and only differ by calling convention. And we will have
> issues with priority of :filter vs. :export if both happen to be
> present (e.g. when a user defines a custom :export in personal config).

Fair point. :export should have precedence to not break user 
customization. Those who define :filter should set :export to nil. It is 
not perfect, but the extra argument is worse from my point of view.

>>> Then, if the :export function returns non-string, the return value is
>>> further processed as (org-export-data *return-value* info).
>>
>> Do you mean something like the following?
>>
>> (defun org-man-export (link description backend)
>>     "Export a man page LINK with DESCRIPTION.
>> BACKEND is the current export backend."
>>     (org-element-create-link
>>      (format "http://man.he.net/?topic=%s&section=all" link)
>>      description))
> 
> Yes.

It is nice idea for most backends, but it is unclear for me what the 
following function should return for ox-ascii

Ihor Radchenko. Re: Exporting elisp: and shell: links. Sun, 08 Oct 2023 
09:48:07 +0000.
https://list.orgmode.org/87r0m5phrc.fsf@localhost
> +(defun org-link--export-code (path description _ info &optional lang)
> +  "Export executable link with PATH and DESCRIPTION.
> +INFO is the current export info plist.
> +LANG is the language name, as in #+begin_src lang.  For example, \"elisp\"
> +or \"shell\"."
> +  (concat
> +   (org-export-data
> +    (org-element-create
> +     'inline-src-block
> +     `( :language ,lang
> +        :value ,path
> +        :parameters ":exports code :noweb no :eval never"))
> +    info)
> +   (when description (format " (%s)" description))))

Source code should be exported inline or as a note depending on 
preferences. This case exported element is not a link, so description 
should be treated separately.

Re: [RFC][PATCH v2] Allow to export to ascii custom link types as notes

[Ihor Radchenko]

Max Nikulin <manikulin@gmail.com> writes:

>> We can alternatively check function arity.
>
> 5 unnamed arguments for functions that are supposed to be implemented by 
> users looks rather close to a border when it becomes fragile. The 
> language does not enforce type checking for user-supplied functions and 
> users would not bother as well. Multi-argument functions was a painful 
> experience with FORTRAN for me (fortunately I was not deeply involved).

Makes sense.

>>> Do you mean something like the following?
>>>
>>> (defun org-man-export (link description backend)
>>>     "Export a man page LINK with DESCRIPTION.
>>> BACKEND is the current export backend."
>>>     (org-element-create-link
>>>      (format "http://man.he.net/?topic=%s&section=all" link)
>>>      description))
>> 
>> Yes.
>
> It is nice idea for most backends, but it is unclear for me what the 
> following function should return for ox-ascii
>
> Ihor Radchenko. Re: Exporting elisp: and shell: links. Sun, 08 Oct 2023 
> 09:48:07 +0000.
> https://list.orgmode.org/87r0m5phrc.fsf@localhost
>> +(defun org-link--export-code (path description _ info &optional lang)
>> +  "Export executable link with PATH and DESCRIPTION.
>> +INFO is the current export info plist.
>> +LANG is the language name, as in #+begin_src lang.  For example, \"elisp\"
>> +or \"shell\"."
>> +  (concat
>> +   (org-export-data
>> +    (org-element-create
>> +     'inline-src-block
>> +     `( :language ,lang
>> +        :value ,path
>> +        :parameters ":exports code :noweb no :eval never"))
>> +    info)
>> +   (when description (format " (%s)" description))))
>
> Source code should be exported inline or as a note depending on 
> preferences. This case exported element is not a link, so description 
> should be treated separately.

In this scenario, :filter function may transform :raw-path in the link
object, replacing it with
(org-export-data (org-element-create-inline-src-block ...) info).

Or we may arrange ox-ascii to export :raw-link object

(format "[%s] <%s>" anchor (org-export-data (org-element-property :raw-link link) info))

Then, I imagine `org-link--export-code' to do something like

(unless (org-element-property :org-link-code-exported link)
 (setq link (org-element-copy link))
 (org-element-put-property link :org-link-code-exported t)
 (org-element-put-property :raw-link (org-element-create-inline-src-block ...)))

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: [RFC][PATCH v2] Allow to export to ascii custom link types as notes

[Max Nikulin]

On 08/11/2023 17:45, Ihor Radchenko wrote:
> (unless (org-element-property :org-link-code-exported link)
>   (setq link (org-element-copy link))
>   (org-element-put-property link :org-link-code-exported t)
>   (org-element-put-property :raw-link (org-element-create-inline-src-block ...)))

 From my point of view a non-trivial element as :raw-link is a more ugly 
kludge than returning a `cons'. Perhaps a fragment of plain text with 
e.g. attr_ascii_note attribute set to inline source block is a better 
alternative.

Re: [RFC][PATCH v2] Allow to export to ascii custom link types as notes

[Ihor Radchenko]

Max Nikulin <manikulin@gmail.com> writes:

> On 08/11/2023 17:45, Ihor Radchenko wrote:
>> (unless (org-element-property :org-link-code-exported link)
>>   (setq link (org-element-copy link))
>>   (org-element-put-property link :org-link-code-exported t)
>>   (org-element-put-property :raw-link (org-element-create-inline-src-block ...)))
>
>  From my point of view a non-trivial element as :raw-link is a more ugly 
> kludge than returning a `cons'. Perhaps a fragment of plain text with 
> e.g. attr_ascii_note attribute set to inline source block is a better 
> alternative.

I think that a middle ground could be introducing pseudo objects, like
what we do in ox-latex: See latex-math-block, latex-matrices,
`org-latex-math-block-tree-filter', `org-latex-matrices-tree-filter',
and the corresponding transcoders.

We can introduce a special ox-ascii-specific object `object-with-note'
that will be exported by ox-ascii according to
`org-ascii-links-to-notes' settings. Then, we can transform link objects
into `object-with-note' that will later be used in
`org-ascii--describe-links'.

WDYT?

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: [RFC][PATCH v2] Allow to export to ascii custom link types as notes

[Max Nikulin]

On 08/11/2023 18:16, Ihor Radchenko wrote:
> We can introduce a special ox-ascii-specific object `object-with-note'
> that will be exported by ox-ascii according to
> `org-ascii-links-to-notes' settings. Then, we can transform link objects
> into `object-with-note' that will later be used in
> `org-ascii--describe-links'.

I am in doubts if it is a bright idea to transform in place passed link 
object inside `org-ascii-link'.

I see 2 ways:
- Use ad-hoc object-with-note org-element object instead of `cons' in my 
patch (rather cosmetic change).
- Introduce :filter property for links that is called before export 
pass. These functions may return arbitrary elements instead of original 
links. For ox-ascii a dedicated transcoder for object-with-note is 
added. Only custom link types having :export property are processed by 
`org-ascii-link'.

Re: [RFC][PATCH v2] Allow to export to ascii custom link types as notes

[Ihor Radchenko]

Max Nikulin <manikulin@gmail.com> writes:

> On 08/11/2023 18:16, Ihor Radchenko wrote:
>> We can introduce a special ox-ascii-specific object `object-with-note'
>> that will be exported by ox-ascii according to
>> `org-ascii-links-to-notes' settings. Then, we can transform link objects
>> into `object-with-note' that will later be used in
>> `org-ascii--describe-links'.
>
> I am in doubts if it is a bright idea to transform in place passed link 
> object inside `org-ascii-link'.

> I see 2 ways:
> - Use ad-hoc object-with-note org-element object instead of `cons' in my 
> patch (rather cosmetic change).
> - Introduce :filter property for links that is called before export 
> pass. These functions may return arbitrary elements instead of original 
> links. For ox-ascii a dedicated transcoder for object-with-note is 
> added. Only custom link types having :export property are processed by 
> `org-ascii-link'.

By "transform", I meant return `object-with-note'. Basically, the second
item in your list.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>