Re: [PATCH v4] ol.el: add description format parameter to org-link-parameters

[Max Nikulin]

On 08/07/2022 02:57, Hugo Heagren wrote:
> Since the last version of this patch, I have:

Thank you, this version should be more reliable.

> tl;dr The question is: what is the Good Behaviour when
> :default-description is set to something, which is meant to return a
> string and returns 'nil instead? Should it be treated like an empty
> string, or as an error?
Just an idea: if the :default-description function returns "" then use 
empty description, if it returns nil then try 
`org-link-make-description-function'.

Unsure if it is better but I would consider `or' instead of `cond':

(or description
    (let ((make (org-link-get-parameter type :default-description)))
     (and make (condition-case ; ...
    )))
    (and org-link-make-description-function
         (condition-case ; ...
    ))
    desc)

So it becomes a kind of responsibility chain and nil becomes a valid and 
useful value.

I am in doubts concerning "default-description" as the parameter name. I 
would consider either more specific "insert-description" or shorter 
"description". Concerning the former, sometimes I do not mind to have 
default description for export shared by most of backends without 
necessity to explicitly write :export function handling all backends. 
E.g. for <info:org#Protocols> generate 
https://orgmode.org/manual/Protocols.html target and 'info "(org) 
Protocols"' description that is suitable for LaTeX/PDF, HTML, Markdown. 
If something like this were implemented, default-description would 
become ambiguous if it is related to insert or to export.

> +(defmacro test-ol-with-link-parameters-as (type parameters &rest body)
[...]
> +  ;; Copy all keys in `parameters' and their original values to
> +  ;; `orig-parameters'. For `parity': nil = odd, non-nill = even
> +  `(let (parity orig-parameters)
> +     (dolist (p ',parameters)

Have I missed something or the whole macro may be simplified to just 
copy `org-link-parameters'?

  `(let ((org-link-parameters (copy-tree org-link-parameters)))
     (org-link-set-parameters ,type ,@parameters)
     ,@body))

Otherwise `gensym'-generated name should be used instead of hardcoded 
rtn to avoid accidental modification of the variable by the body code:

> +         (let ((_ (org-link-set-parameters ,type ,@parameters))
> +               ;; Do body
> +               (rtn (progn ,@body)))

In addition, `declare' form should be added to `defmacro' to specify 
which argument is considered as its body.

> +    (setq type
> +          (cond

My opinion is that it should be inside
   (let ((initial-input ...
and maybe even be a sibling of
   (def (org-link-get-parameter type
to keep related code more local.

> -             ((not org-link-make-description-function) desc)
> +              (desc)
> +              ((org-link-get-parameter type :default-description)
> +               (let ((def (org-link-get-parameter type :default-description)))

I have not tested, so I may be wrong in respect to the following. It 
seems, you rises priority of desc value that earlier was a fallback. The 
reason why I am in doubts, is that it seems, desc is initialized from 
current link description when point is withing an existing link and in 
such cases desc likely should be preserved. I can not say that I like 
that it is responsibility of all description functions to return the 
desc argument if it is supplied.

>               (t (condition-case nil
>                      (funcall org-link-make-description-function link desc)

Notice that before you modification `funcall' was guarded by "(not 
org-link-make-description-function)" test.

I like the idea of description specific to link type and it is sour that 
previous attempts to implement the feature was not completed.