Re: Exporting elisp: and shell: links

[Ihor Radchenko]

Max Nikulin  writes:

>> May you elaborate? I am not talking about implementation details, but
>> about the reasonable defaults for the export. Not necessary ASCII, but
>> other backends as well.
> I am rather skeptical concerning a variant that is pleasant to read in 
> all cases. That is why I suggest to provide tools that allow to 
> customize export accordingly their writing styles.

Maybe then we can simply provide default :export for html and latex, but
nothing else?

> ASCII is a special case since it uses end note style to present link 
> targets.
>
> Whether code is added before link description or after it, either 
> parenthesis are used or not, the following functions may be convenient 
> for Org and for users:
> - export argument as inline source block
> - add an item to ASCII list of links

I wouldn't oppose improving ox-ascii API. Feel free to submit a patch.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at .
Support Org development at ,
or support my work at 

Re: Exporting elisp: and shell: links

[Max Nikulin]

On 12/10/2023 18:35, Ihor Radchenko wrote:

Max Nikulin writes:


I like more how ox-ascii (without the
proposed diff) handles the situation via footnote-like link.


That is why I believe that extracting fragments of code into helper
functions is important. If ox-ascii.el had a function that adds an item
to link list then ol.el would use it to add src_elisp elements to this list.


May you elaborate? I am not talking about implementation details, but
about the reasonable defaults for the export. Not necessary ASCII, but
other backends as well.
I am rather skeptical concerning a variant that is pleasant to read in 
all cases. That is why I suggest to provide tools that allow to 
customize export accordingly their writing styles.


ASCII is a special case since it uses end note style to present link 
targets.


Whether code is added before link description or after it, either 
parenthesis are used or not, the following functions may be convenient 
for Org and for users:

- export argument as inline source block
- add an item to ASCII list of links

Re: Exporting elisp: and shell: links

[Ihor Radchenko]

Max Nikulin  writes:

>> I like more how ox-ascii (without the
>> proposed diff) handles the situation via footnote-like link.
>
> That is why I believe that extracting fragments of code into helper 
> functions is important. If ox-ascii.el had a function that adds an item 
> to link list then ol.el would use it to add src_elisp elements to this list.

May you elaborate? I am not talking about implementation details, but
about the reasonable defaults for the export. Not necessary ASCII, but
other backends as well.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at .
Support Org development at ,
or support my work at 

Re: Exporting elisp: and shell: links

[Rudolf Adamkovič]

Ihor Radchenko  writes:

> I am not sure if I like it.

Me neither.  The problem is in the parentheses, IMHO.  The Lisp
expression is enclosed in parentheses and so is the description:

  (message "Hello") (Message Hello)

That indeed looks confusing!  How about we swap the sides and remove one
pair of parentheses?  That would give:

  Message Hello (message "Hello")

Rudy
-- 
"Genius is 1% inspiration and 99% perspiration."
-- Thomas Alva Edison, 1932

Rudolf Adamkovič  [he/him]
Studenohorská 25
84103 Bratislava
Slovakia

Re: Exporting elisp: and shell: links

[Max Nikulin]

On 09/10/2023 19:12, Ihor Radchenko wrote:

Valid, but I am more concerned about the whole idea. I _feel_ that

code (description)

does not look nice in html export.


It is minor in comparison with invalid HTML that may be generated by 
current code. I am unsure if a better variant exist, but to evaluate it 
several real life examples are required.



I like more how ox-ascii (without the
proposed diff) handles the situation via footnote-like link.


That is why I believe that extracting fragments of code into helper 
functions is important. If ox-ascii.el had a function that adds an item 
to link list then ol.el would use it to add src_elisp elements to this list.

Re: Exporting elisp: and shell: links

[Ihor Radchenko]

Max Nikulin  writes:

>> +(defun org-link--export-code (path description _ info  lang)
>
> I think, the fragment above should be a public function that is a 
> building block for users who want to override export of links having 
> descriptions.

Sure, but that's minor.

>> +   (when description (format " (%s)" description
>
> I hope, path was never added as default description, so checks (or 
> (string-equal path description) (string-equal (concat type ":" path) 
> description))) are not necessary to avoid annoying repetitions.

Valid, but I am more concerned about the whole idea. I _feel_ that

code (description)

does not look nice in html export. I like more how ox-ascii (without the
proposed diff) handles the situation via footnote-like link.

That's my personal preferences though. Which is why I want to hear more
opinions. In particular, I encourage others to play around with various
exported documents with and without the diff and comment on how they
look.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at .
Support Org development at ,
or support my work at 

Re: Exporting elisp: and shell: links

[Max Nikulin]

On 08/10/2023 16:48, Ihor Radchenko wrote:

+++ b/lisp/ol.el
@@ -1377,7 +1377,29 @@ (defun org-link--open-elisp (path _)
 (call-interactively (read path
 (user-error "Abort")))
 
-(org-link-set-parameters "elisp" :follow #'org-link--open-elisp)

+(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)


I think, the fragment above should be a public function that is a 
building block for users who want to override export of links having 
descriptions.



+   (when description (format " (%s)" description


I hope, path was never added as default description, so checks (or 
(string-equal path description) (string-equal (concat type ":" path) 
description))) are not necessary to avoid annoying repetitions.

Re: Exporting elisp: and shell: links

[Ihor Radchenko]

Rudolf Adamkovič  writes:

>> Still, it would be nice to have _a_ variant compared to the current
>> state of affairs.
>
> Agreed.  If the link has no description, we can do a great job on
> exporting it.  Half of the victory, right there!
>
> Also, how about the following /simple/ idea for the description:
>
>   [[elisp:(server-start)][Launch Server]]
>   [[elisp:(server-start)][=M-x server-start RET=]]
>   
>   src_elisp[:exports code]{(server-start)} (Launch Server)
>   src_elisp[:exports code]{(server-start)} (=M-x server-start RET=)
>
> TL;DR We export the description, if any, in parentheses after the code.

See the attached diff, implementing your suggestion.
I am not sure if I like it.

Consider the following example file:


#+options: toc:nil author:nil

[[elisp:(message "Hello")]]

[[elisp:(message "Hello")][Message Hello]]


Without the diff, exporting to ASCII yields




[Message Hello]


[Message Hello] 


with the diff:


`(message "Hello")'

`(message "Hello")' (Message Hello)
---

For markdown:

without diff:
---
<(message "Hello")>

[Message Hello]((message "Hello"))

---

with:
---
`(message "Hello")`

`(message "Hello")` (Message Hello)
---

For html:

without diff:

with:
diff --git a/lisp/ol.el b/lisp/ol.el
index 20aab6bb8..d537709ac 100644
--- a/lisp/ol.el
+++ b/lisp/ol.el
@@ -1377,7 +1377,29 @@ (defun org-link--open-elisp (path _)
 		 (call-interactively (read path
 (user-error "Abort")))
 
-(org-link-set-parameters "elisp" :follow #'org-link--open-elisp)
+(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
+
+(defun org-link--export-elisp (path description _ info)
+  "Export elisp: link with PATH and DESCRIPTION according to INFO channel."
+  (org-link--export-code path description nil info "emacs-lisp"))
+
+(org-link-set-parameters
+ "elisp"
+ :follow #'org-link--open-elisp
+ :export #'org-link--export-elisp)
 
  "file" link type
 (org-link-set-parameters "file" :complete #'org-link-complete-file)
@@ -1435,7 +1457,14 @@ (defun org-link--open-shell (path _)
 		  clean-buffer-list-kill-buffer-names
 (user-error "Abort")))
 
-(org-link-set-parameters "shell" :follow #'org-link--open-shell)
+(defun org-link--export-shell (path description _ info)
+  "Export shell: link with PATH and DESCRIPTION according to INFO channel."
+  (org-link--export-code path description nil info "shell"))
+
+(org-link-set-parameters
+ "shell"
+ :follow #'org-link--open-shell
+ :export #'org-link--export-shell)
 
 
 ;;; Interactive Functions


-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at .
Support Org development at ,
or support my work at 

Re: Exporting elisp: and shell: links

[Rudolf Adamkovič]

Ihor Radchenko  writes:

> Still, it would be nice to have _a_ variant compared to the current
> state of affairs.

Agreed.  If the link has no description, we can do a great job on
exporting it.  Half of the victory, right there!

Also, how about the following /simple/ idea for the description:

  [[elisp:(server-start)][Launch Server]]
  [[elisp:(server-start)][=M-x server-start RET=]]
  
  src_elisp[:exports code]{(server-start)} (Launch Server)
  src_elisp[:exports code]{(server-start)} (=M-x server-start RET=)

TL;DR We export the description, if any, in parentheses after the code.

Rudy
-- 
"One can begin to reason only when a clear picture has been formed in
the imagination."
-- Walter Warwick Sawyer, Mathematician's Delight, 1943

Rudolf Adamkovič  [he/him]
Studenohorská 25
84103 Bratislava
Slovakia

Re: Exporting elisp: and shell: links

[Ihor Radchenko]

Max Nikulin  writes:

> I am afraid, there is no variant that fits for all cases even in a 
> particular document.

Still, it would be nice to have _a_ variant compared to the current
state of affairs.

As for extra customization, it totally depends on the interest in this
functionality. If not many people are interested, I'd put one variant in
Org and left non-standard export to the users to customize via :export
link property.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at .
Support Org development at ,
or support my work at 

Re: Exporting elisp: and shell: links

[Max Nikulin]

On 23/09/2023 06:43, Rudolf Adamkovič wrote:

Ihor Radchenko writes:


Another idea: use code as description displayed in the tooltip (in html).
Copy-on-clip also makes sense.

Yet another idea: export code inside a footnote. This will work across
all the backends.


Yet another, another idea: export the description as a Lisp comment,
after converting it to plain text.  To use Max's example:

src_elisp[:exports code]{(server-start) ; Launch server}
src_elisp[:exports code]{(server-start) ; `M-x server-start RET'}


I do not think, code with comments is suitable for inline source blocks, 
such code should occupy a dedicated line.


I am afraid, there is no variant that fits for all cases even in a 
particular document. It would be great to mark specific links, which way 
each one should be exported:


You should run
[[elisp:(server-start)][=M-x server-start=]].
Or you can [[elisp:(identity "a")][run it]].

You should run
M-x server-start.
Or you can run it ->
(identity "a").

I know, Ihor do not like the idea of attributes for inline objects
due to complexity of current implementation of parser for #+attr_html:

Ihor Radchenko. Re: [HELP] Fwd: Org format as a new standard source 
format for GNU manuals. Mon, 03 Oct 2022 12:36:20 +0800. 
https://list.orgmode.org/87r0zpy14r.fsf@localhost

Re: Exporting elisp: and shell: links

[Rudolf Adamkovič]

Ihor Radchenko  writes:

> Another idea: use code as description displayed in the tooltip (in html).
> Copy-on-clip also makes sense.
>
> Yet another idea: export code inside a footnote. This will work across
> all the backends.

Yet another, another idea: export the description as a Lisp comment,
after converting it to plain text.  To use Max's example:

src_elisp[:exports code]{(server-start) ; Launch server}
src_elisp[:exports code]{(server-start) ; `M-x server-start RET'}

Rudy
-- 
"Logic is a science of the necessary laws of thought, without which no
employment of the understanding and the reason takes place."
-- Immanuel Kant, 1785

Rudolf Adamkovič  [he/him]
Studenohorská 25
84103 Bratislava
Slovakia

Re: Exporting elisp: and shell: links

[Ihor Radchenko]

Max Nikulin  writes:

>> As a user, I would expect
>> 
>>[[elisp:(identity "a")]]
>> 
>> to be export-equivalent to
>> 
>>src_elisp[:exports code]{(identity "a")}
>> 
>> across all backends.

Makes sense.

>>> What is your expectation for links having description?
>>>
>>> [[elisp:(identity "a")][Run it]]
>> 
>> Good point!  Perhaps we just need to find a
>> good symbol that would work well between the
>> Elisp code and the description?
>> 
>> For example
>> 
>>/Run it/ \to src_elisp[:exports code]{(identity "a")}
>> 
>> exports to ASCII as
>> 
>>/Run it/ -> `(identity "a")'
>> 
>> Of course, \to could be something else...

Another idea: use code as description displayed in the tooltip (in html).
Copy-on-clip also makes sense.

Yet another idea: export code inside a footnote. This will work across
all the backends.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at .
Support Org development at ,
or support my work at 

Re: Exporting elisp: and shell: links

[Max Nikulin]

On 19/09/2023 07:10, Rudolf Adamkovič wrote:

Max Nikulin  writes:


Do you think a label specifying language should be added to code
snippets, e.g. (identity "a") or it is
useless and may cause undesired noise for screen reader users? What
about LaTeX?


As a user, I would expect

   [[elisp:(identity "a")]]

to be export-equivalent to

   src_elisp[:exports code]{(identity "a")}

across all backends.


(defun org-link-export-eval-link-no-descr
(type path descr backend info)
  (unless descr
(let ((element
   (org-element-create
'inline-src-block
(list :language type
  :value path
  :parameters ":exports code :noweb no :eval never"
  (org-export-data element info

(defun org-link-make-export-eval-link-no-descr (type)
  (lambda (path descr backend info)
   (org-link-export-eval-link-no-descr
type path descr backend info)))

(dolist (type '("elisp" "shell"))
  (org-link-set-parameters
   type
   :export (org-link-make-export-eval-link-no-descr type)))


What is your expectation for links having description?

[[elisp:(identity "a")][Run it]]


Good point!  Perhaps we just need to find a
good symbol that would work well between the
Elisp code and the description?

For example

   /Run it/ \to src_elisp[:exports code]{(identity "a")}

exports to ASCII as

   /Run it/ -> `(identity "a")'

Of course, \to could be something else...


I have another example:

   [[elisp:(server-start)][=M-x server-start RET=]]

suitable for a printed document.

From my point of view, it is better either to drop link path completely 
or to add a button to copy the code to clipboard. Repetition is undesired.


So I am unsure if it is possible to choose unambiguous rules for export 
of elisp and shell links.

Re: Exporting elisp: and shell: links

[Rudolf Adamkovič]

Max Nikulin  writes:

> Do you think a label specifying language should be added to code 
> snippets, e.g. (identity "a") or it is 
> useless and may cause undesired noise for screen reader users? What 
> about LaTeX?

As a user, I would expect

  [[elisp:(identity "a")]]

to be export-equivalent to

  src_elisp[:exports code]{(identity "a")}

across all backends.

[If Org works as it should, then that solves
screen readers, LaTeX, etc.]

> What is your expectation for links having description?
>
>[[elisp:(identity "a")][Run it]]

Good point!  Perhaps we just need to find a
good symbol that would work well between the
Elisp code and the description?

For example

  /Run it/ \to src_elisp[:exports code]{(identity "a")}

exports to ASCII as

  /Run it/ -> `(identity "a")'

Of course, \to could be something else...

WDYT?

Rudy
-- 
"Thinking is a momentary dismissal of irrelevancies."
-- Richard Buckminster Fuller, 1969

Rudolf Adamkovič  [he/him]
Studenohorská 25
84103 Bratislava
Slovakia