Karthik Chikmagalur <karthikchikmaga...@gmail.com> writes:
> 1. Patch 0001 is the code patch from before, with the warnings from make
> addressed.
>
> 2. Patch 0002 is the documentation patch, which adds to ORG-NEWS and the
> manual. There are two new sections -- one is in the appendix under
> "Hacking", and shows how to add a preview function for a link type
> (along with a code example).
Thanks!
See my comments on the documentation patch below.
> -** Images
> +** Images and link previews
> +
> +Org mode can preview hyperlinks in the buffer as images or with other
> +decorations.
May put a link to [*Hyperlinks] here.
Also, this reads awkward. Maybe something like
Org mode can display previews of [[*Hyperlinks][hyperlinks]] inside
Org buffers. By default, only image links[fn::previews are
available =file:= and =attachment:= links to image files; Emacs
should be able to display the linked images (see ~image-types~
variable)] can be previewed - the images are displayed in place of
the link path.
You can customize the previews as described in [*Adding Hyperlink
preview] section. The custom previews do not have to display images
- any kind of [[info:elisp#Overlay Properties][display decoration]]
can be used.
> +*** External link previews
> +:PROPERTIES:
> +:DESCRIPTION: Preview links in the buffer.
> +:END:
> +
> +Org mode can preview [[* External links][External links]] as inline
> +images or with other decorations. This requires support for the
> +corresponding link types to be available[fn:: To add support for or to
> +modify how links of a certain type are previewed, see .]. By default
^^^^^
> +Org mode includes support for previewing file and attachment links for
> +image files (see [[* Images][Images]]).
The first sentence in the parent section and the first sentence here are
basically identical. As I suggested above, let's move these things
up. (Feel free to modify my version as you see fit.)
> +Supported link types can be previewed within the buffer with the
> +following commands:
If possible, try to use active voice. We are talking to users in the
manual:
You can preview the supported link types in the whole buffer, in
current section, region, or at point.
> + By default, only image links without a description are displayed.
> + You can force displaying previews for all supported links using
> + numeric argument to toggle all the images in current section (~1~
> + argument) or the whole buffer (~11~ argument).
This is not accurate. C-1 argument will act just as no argument: display
links at point/region/section depending on the context.
Looks like the docstring wrt C-1/C-11 args should be improved.
> + #+vindex: org-startup-with-inline-images
> + You can ask for inline link previews to be displayed at startup by
> + configuring the variable ~org-startup-with-inline-images~[fn:: The
> + variable ~org-startup-with-inline-images~ can be set within a buffer
> + with the =STARTUP= options =inlineimages= and =noinlineimages=.].
Org mode can display link previews automatically when opening
buffers. Either customize ~org-startup-with-inline-images~ or use
in-buffer =#+STARTUP: inlineimages= keyword to enable the previews.
=#+STARTUP: noinlineimages= will disable the previews in specific
buffer.
Also, since we are generalizing things away from images, maybe we should
introduce some aliases to ~org-startup-with-inline-images~ and to the
startup option values. Something like ~org-startup-with-link-previews~
and similar to startup option.
> +- {{{kbd(C-c C-x C-M-v)}}} (~org-link-preview-refresh~) ::
> +
> + #+kindex: C-c C-x C-M-v
> + #+findex: org-link-preview-refresh
> + Assure inline display of external link previews in the buffer and
> + refresh them.
"the whole buffer" maybe.
> +Such images can be displayed within the buffer with the
> +~org-link-preview~ and associated command, see [[*External link previews]].
This sentence reads awkwardly after the previous section that already
talked about previews and ~org-link-preview~ command.
We can write
When [[*External link previews][link previews]] are displayed as
images, the image size and alignment can be further customized.
> #+vindex: org-cycle-inline-images-display
> Inline images can also be displayed when cycling the folding state.
> @@ -21794,6 +21833,65 @@ ** Adding Hyperlink Types
> topic. It also provides a default description. The function
> ~org-insert-link~ can insert it back into an Org buffer later on.
I suspect that it belongs to the previous section - cycling should work
for all the link previews, not just images.
> +2. The value of the =:preview= parameter must be a function that
> + accepts three arguments:
> + - an overlay placed from the start to the end of the link,
> + - the link path, as a string, and
> + - the link element.
element -> syntax node
> + It must return a non-nil value to indicate preview success.
... and your example can sometimes return nil, which is confusing.
We should explain what nil means as a return value as well.
> --- a/etc/ORG-NEWS
> +++ b/etc/ORG-NEWS
> @@ -24,26 +24,38 @@ Previously, =C-c C-x C-v= always toggled image display in
> the whole
> buffer (or narrowed part of the buffer). With prefix argument, it
> also forced displaying image links with description.
> ...
> +2. Otherwise, if there is an image at point, it is toggled. If there
> + is no image at point, images in the current entry are previewed
Aside: I am wondering if we should also attach preview toggle to <TAB>
when ~org-cycle-inline-images-display~ is non-nil and there is a link at
point.
> +*** New option ~org-link-preview-batch-size~
> +
> +Org link previews are generated a few at a time, in batches. This
asynchronously
> +option controls the number of links that are previewed in each batch.
> +
> +*** New option ~org-link-preview-delay~
> +
> +Org link previews are generated asynchronously. This option controls
> +the minimum idle time in seconds between previews of batches of links.
--
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>
