Re: [PATCH v2] ol-info: Define :insert-description function

[Max Nikulin <manikulin@gmail.com>]

On 20/08/2022 14:29, Ihor Radchenko wrote:
> Max Nikulin writes:
> 
>> On 19/08/2022 11:28, Ihor Radchenko wrote:
>>> Max Nikulin writes:
>>>
>>>> +(defun org-info--link-file-node (path)
>>>> +  "Extract file name and node from info link PATH.
>>>> +
>>>> +Return cons consisting of file name and node name or \"Top\" if node
>>>> +part is not specified. Components may be separated by \":\" or by \"#\"."
>>>
>>> It looks like the docstring does not match what the function actually
>>> returns.
>>
>> It returns a cons, doesn't it? Is it confusing that separator for
>> components is related to the argument?
> 
> It is confusing that cons consist of _file name_ and node name.
> However, the function may return non-file as car of the cons.

"dir" should not appear in well-formed links <info:file#node>. If a user 
adds "info:" links then it is unlikely that their has never used info 
and has never seen directory index. Moreover I do not see real problem 
since it is considered as a virtual info file:

https://git.savannah.gnu.org/cgit/emacs.git/tree/lisp/info.el#n2344
(add-to-list 'Info-virtual-files
	     '("\\`dir\\'" ; ...

After all, it is an internal function and I am still unsure that I have 
chosen the best variant. I believed that underspecified behavior here 
may give less harm than making some 3rd party code relying on the 
proposed variant.

I can drop "(dir)" special case to consider incomplete links as invalid 
ones. The only problem is test cases for escaping of various characters 
since they use links without file name as the input, but they may be 
easily adjusted by adding some file name.

There is huge room for improvements in "ol-info.el", e.g. other virtual 
files such as "(*History*)" may signal an error during HTML export.