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

[Ihor Radchenko]

Max Nikulin  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 .
Support Org development at ,
or support my work at 

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  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 .
Support Org development at ,
or support my work at 

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  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=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 +.
> https://list.orgmode.org/87r0m5phrc.fsf@localhost
>> +(defun org-link--export-code (path description _ info  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 .
Support Org development at ,
or support my work at 

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=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 +.

https://list.orgmode.org/87r0m5phrc.fsf@localhost

+(defun org-link--export-code (path description _ info  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  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=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 .
Support Org development at ,
or support my work at 

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=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  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 .
Support Org development at ,
or support my work at 

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

[Max Nikulin]

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.
From f6891e33522c1ec321d01d8c3986fbf789c79224 Mon Sep 17 00:00:00 2001
From: Max Nikulin 
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
 
+(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] \n"))
+  (should ; No description.
+   (string-equal
+(org-export-string-as
+ "Link [[tstdflt:path-no-descr]] without description (note)."
+ 'ascii t)
+"Link  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] ().\n"))
+  (should ; No description.
+   (string-equal
+(org-export-string-as
+ "Inline link [[tstdflt:path-no-descr]] without description."
+ 'ascii t)
+"Inline link  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