[BUG] Documentation fix needed in "4.4 External Links" [9.6 ( @ /home/dsmasterson/.emacs.d/elpa/org-9.6/)]

[BUG] Documentation fix needed in "4.4 External Links" [9.6 ( @ /home/dsmasterson/.emacs.d/elpa/org-9.6/)]

[David Masterson]

Remember to cover the basics, that is, what you expected to happen and
what in fact did happen.  You don't know how to make a good report?  See

     https://orgmode.org/manual/Feedback.html#Feedback

Your bug report will be posted to the Org mailing list.
------------------------------------------------------------------------

The documentation page for "4.4 External Links" could provide the
answers to following questions:

1. What "file types" are supported by link type "file"?

2. If #1 depends on some org variable settings, can you mention what
variables control the answer to #1?

Emacs  : GNU Emacs 27.1 (build 1, x86_64-pc-linux-gnu, X toolkit, Xaw3d scroll bars)
 of 2021-03-27, modified by Debian
Package: Org mode version 9.6 ( @ /home/dsmasterson/.emacs.d/elpa/org-9.6/)
-- 
David Masterson

Re: [BUG] Documentation fix needed in "4.4 External Links" [9.6 ( @ /home/dsmasterson/.emacs.d/elpa/org-9.6/)]

[Ihor Radchenko]

David Masterson <dsmasterson@gmail.com> writes:

> The documentation page for "4.4 External Links" could provide the
> answers to following questions:
>
> 1. What "file types" are supported by link type "file"?

All. Though I am not sure what you mean by "supported".

> 2. If #1 depends on some org variable settings, can you mention what
> variables control the answer to #1?

If you mean "can open", then see the next section.

-- 
Ihor Radchenko // yantar92,
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>

Re: [BUG] Documentation fix needed in "4.4 External Links" [9.6 ( @ /home/dsmasterson/.emacs.d/elpa/org-9.6/)]

[David Masterson]

Ihor Radchenko <yantar92@posteo.net> writes:

> David Masterson <dsmasterson@gmail.com> writes:
>
>> The documentation page for "4.4 External Links" could provide the
>> answers to following questions:
>>
>> 1. What "file types" are supported by link type "file"?
>
> All. Though I am not sure what you mean by "supported".

As in, if you follow (open?) a file link, how is the file handled
(particularly, for me, JPG, PNG, MP4, etc.)?  What's the process by
which an image gets inlined?  Do I have to install some image processor
to do that?  If so, which?  Or can I adjust a variable to use my chosen
image processor? 

>> 2. If #1 depends on some org variable settings, can you mention what
>> variables control the answer to #1?
>
> If you mean "can open", then see the next section.

Ahh, maybe I am in the wrong section.  I think, what I want is
org-open-at-point (which could be mentioned in 4.4), but it's
documentation string just says the linked file will be opened by "an
appropriate application".  I assume that that means some Elisp function
is called that cross-references the file type with appropriate
application.  And that I could add to or adjust the cross-reference list
for new/modified file types.  It would be nice to mention that list
variable so that I could trace the process further and determine what to
do (like install the appropriate application).

Does this help for what I'm looking for?

-- 
David Masterson

Re: [BUG] Documentation fix needed in "4.4 External Links" [9.6 ( @ /home/dsmasterson/.emacs.d/elpa/org-9.6/)]

[Ihor Radchenko]

David Masterson <dsmasterson@gmail.com> writes:

>>> 2. If #1 depends on some org variable settings, can you mention what
>>> variables control the answer to #1?
>>
>> If you mean "can open", then see the next section.
>
> Ahh, maybe I am in the wrong section.  I think, what I want is
> org-open-at-point (which could be mentioned in 4.4), but it's
> documentation string just says the linked file will be opened by "an
> appropriate application".  I assume that that means some Elisp function
> is called that cross-references the file type with appropriate
> application.  And that I could add to or adjust the cross-reference list
> for new/modified file types.  It would be nice to mention that list
> variable so that I could trace the process further and determine what to
> do (like install the appropriate application).
>
> Does this help for what I'm looking for?

4.5 Handling Links
...
‘C-c C-o’ (‘org-open-at-point’)
...
     ... Furthermore, it visits text and
     remote files in ‘file’ links with Emacs and select a suitable
     application for local non-text files.  Classification of files is
     based on file extension only.  See option ‘org-file-apps’.  If you
     want to override the default application and visit the file with
     Emacs, use a ‘C-u’ prefix.  If you want to avoid opening in Emacs,
     use a ‘C-u C-u’ prefix.


-- 
Ihor Radchenko // yantar92,
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>

Re: [BUG] Documentation fix needed in "4.4 External Links" [9.6 ( @ /home/dsmasterson/.emacs.d/elpa/org-9.6/)]

[David Masterson]

Ihor Radchenko <yantar92@posteo.net> writes:

> David Masterson <dsmasterson@gmail.com> writes:
>
>>>> 2. If #1 depends on some org variable settings, can you mention what
>>>> variables control the answer to #1?
>>>
>>> If you mean "can open", then see the next section.
>>
>> Ahh, maybe I am in the wrong section.  I think, what I want is
>> org-open-at-point (which could be mentioned in 4.4), but it's
>> documentation string just says the linked file will be opened by "an
>> appropriate application".  I assume that that means some Elisp function
>> is called that cross-references the file type with appropriate
>> application.  And that I could add to or adjust the cross-reference list
>> for new/modified file types.  It would be nice to mention that list
>> variable so that I could trace the process further and determine what to
>> do (like install the appropriate application).
>>
>> Does this help for what I'm looking for?
>
> 4.5 Handling Links
> ...
> ‘C-c C-o’ (‘org-open-at-point’)
> ...
>      ... Furthermore, it visits text and
>      remote files in ‘file’ links with Emacs and select a suitable
>      application for local non-text files.  Classification of files is
>      based on file extension only.  See option ‘org-file-apps’.  If you
>      want to override the default application and visit the file with
>      Emacs, use a ‘C-u’ prefix.  If you want to avoid opening in Emacs,
>      use a ‘C-u C-u’ prefix.

D***, I'm getting old!  These things used to pop out at me in the old
days.  Apologies for the dumb question...  :(

Do you think (some part of) this (semi-)paragraph should be mentioned in
the docstring for 'org-open-at-point' (and 'org-open-at-mouse')? I'm of
the opinion that, if you walk-thru the docstring links, you would get
all the info you'd get in the manual (and more), but not necessarily
explained in a user-friendly form,

-- 
David Masterson

Re: [BUG] Documentation fix needed in "4.4 External Links" [9.6 ( @ /home/dsmasterson/.emacs.d/elpa/org-9.6/)]

[Ihor Radchenko]

David Masterson <dsmasterson@gmail.com> writes:

> Do you think (some part of) this (semi-)paragraph should be mentioned in
> the docstring for 'org-open-at-point' (and 'org-open-at-mouse')? I'm of
> the opinion that, if you walk-thru the docstring links, you would get
> all the info you'd get in the manual (and more), but not necessarily
> explained in a user-friendly form,

https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=edd000f3b

-- 
Ihor Radchenko // yantar92,
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>

Re: [BUG] Documentation fix needed in "4.4 External Links" [9.6 ( @ /home/dsmasterson/.emacs.d/elpa/org-9.6/)]

[David Masterson]

Ihor Radchenko <yantar92@posteo.net> writes:

> David Masterson <dsmasterson@gmail.com> writes:
>
>> Do you think (some part of) this (semi-)paragraph should be mentioned in
>> the docstring for 'org-open-at-point' (and 'org-open-at-mouse')? I'm of
>> the opinion that, if you walk-thru the docstring links, you would get
>> all the info you'd get in the manual (and more), but not necessarily
>> explained in a user-friendly form,
>
> https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=edd000f3b

Possibly good, but should the docstrings for org-open-at-point,
org-open-at-mouse and org-open-file be unified in way so that they track
each other for changes in one of them?

-- 
David Masterson

Re: [BUG] Documentation fix needed in "4.4 External Links" [9.6 ( @ /home/dsmasterson/.emacs.d/elpa/org-9.6/)]

[Ihor Radchenko]

David Masterson <dsmasterson@gmail.com> writes:

>> https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=edd000f3b
>
> Possibly good, but should the docstrings for org-open-at-point,
> org-open-at-mouse and org-open-file be unified in way so that they track
> each other for changes in one of them?

`org-open-at-mouse' simply refers to `org-open-file'.

`org-open-at-point' is a different beast.
This function needs to be refactored into smaller chunks.
Docstring is not the biggest issue there.

-- 
Ihor Radchenko // yantar92,
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>