Max Nikulin <maniku...@gmail.com> 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.
>>> + (if (not path)
>>> + '("dir" . "Top")
>>
>> "dir" is not a file. Also, it is not very clear what "dir" is referring
>> to. Maybe you can add a comment pointing to `org-info-other-documents'?
>
> Try M-x info RET when you do not have *info* buffer and you get "(dir)
> Top" node. It is the directory of info files. If you run "info" without
> argument in shell you will get the same.
Sure. I know this. But see the above. Not every person reading the Org
source is familiar with info conventions.
>>> + (string-match "\\`\\([^#:]*\\)\\(?:[#:]:?\\(.*\\)\\)?\\'" path)
>>> + (let* ((node (match-string 2 path))
>>> + ;; `string-trim' modifies match
>>
>> Here and is several other places, including docstrings, please make sure
>> that the sentences end with "." and are separated with " ".
>
> It was supposed to be a brief phrase rather than complete sentence.
What about other places like the docstring?
Or
+ ;; Unlike (info "dir"), "info dir" shell command opens "(coreutils)dir
invocation"
(missing ".")
probably some more places.
(Of course, this is minor, and I could do it myself; just pointed this
together with other more important comments)
>>> + (cons
>>> + ;; Fallback to "org" is an arbirtrary choice
>>> + ;; and added because "(dir)filename" does not work as "filename".
>>
>> Should this be documented? Or at least mentioned that the behaviour is
>> undefined. And if it is undefined you should not test it in the tests.
>
> The purpose of test is to check that it does not signal some obscure
> error. I am unsure how to handle corner cases, so I am open to
> suggestions. Some considerations
> - `org-info--link-file-node' may return nil when link path is incomplete
> or some value that may help to avoid error handling code paths in callers.
> - <info:> does not look like a valid link but it may be handled like
> shell "info" command without argument, so I chose "(dir)" node. Elisp
> (info) without arguments however may display existing buffer.
> - <info:dir> certainly should be handled as (info "(dir)")
> - <info:dir#elisp> is invalid. Maybe (info "elisp") should be used instead.
> - <info:#Tables> I am unsure in my choice to open (info "(org) Tables").
> Maybe it is better to treat it as "(dir) Tables" and so as "(dir) Top"
> node since "(dir) Top" is quite reasonable for <info:> with empty path.
I am not sure what would be the best here. The main point - whatever
fallback mechanism you choose, please document it in the docstring.
In general, I favour having a fallback more compared to not having any.
--
Ihor Radchenko,
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
