"Christopher M. Miles" <numbchild@gmail.com> writes:

>> Then, for backward compatibility, we may treat any non-nil, non-list
>> (like '(4), '(16), '(64)), non-number (like 1, 11) value as
>> INCLUDE-LINKED. This way, the existing calls like
>> (org-toggle-inline-images t) will not be broken.
> ...
> I prefer this compromise result.
> I updated the patch, Please review it whether it's correct.

I think that C-u C-u unconditionally including linked images is
confusing.

What about using my idea with M-1/M-11 to be interpreted as INCLUDE-LINKED=t?

Also, you did not document in the docstring what happens if ARG is
something like t.

> I did a source code statistics researching of using the function org-toggle-inline-images at two places:
>
> - GitHub: https://github.com/search?q=org-toggle-inline-images&ref=opensearch&type=code&p=3
> (Only package scimax incoke this function with INCLUDE-LINKED argument t)
> - My installed Emacs packages, NO package invoke this function with argument INCLUDE-LINKED.
>
> So lucky this change will not affect lot.

I have found user configs using the argument:

https://github.com/search?q=%22%28org-toggle-inline-images+t%29%22&type=code
https://github.com/search?q=%22%28org-toggle-inline-images+%27%22&type=code

So, please do as I advised - treat non-special ARG values as INCLUDE-LINKED.

Also, looking at the proposed prefix arguments, I feel that it might not
necessarily be the best idea to copy over what org-latex-preview does
exactly. org-latex-preview is not a "toggle", unlike org-toggle-inline-images

What about the following treatment of ARG:

1. No argument, no region selected :: toggle (display or hide dwim) images in current section
2. No argument, region selected: toggle images in region
3. C-u argument :: toggle images in the whole buffer
4. C-u C-u argument, no region selected :: unconditionally hide images in the buffer
5. M-1 argument, no region selected :: display images in current section with INCLUDE-LINKED
6. M-1 argument, region selected :: ... in region ...
7. M-11 argument :: ... in the whole buffer ...
8. Any other argument :: treat as INCLUDE-LINKED = t

And please document all the new arguments in the manual and etc/ORG-NEWS file.

--
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>