Work/47display images

README.adoc

@@ -35,6 +35,7 @@ Here are some of the main features of `adoc-mode`:
 
 - sophisticated highlighting
 - native fontification of code blocks
+- toggle between the display of image links and the display of the corresponding images
 - promote / demote title
 - toggle title type between one line title and two line title
 - adjust underline length of a two line title to match title text's length
@@ -44,9 +45,39 @@ Here are some of the main features of `adoc-mode`:
 === Demo
 
 The highlighting emphasizes on how the output will look like. _All_
-characters are visible, however meta characters are displayed in a faint way.
+characters are visible, however meta characters are displayed in a
+faint way.  An exception are image links.  You can toggle between
+the display of the link text and the linked image.
 
-image:images/adoc-mode.png[alt=screenshot]
+image::images/adoc-mode.png[alt=screenshot]
+
+== Usage
+
+Adoc-mode is designed for intuitive use. Most features are available
+from the _AsciiDoc_ menu in the menu bar.
+
+This section only describes some not so obvious features.
+
+=== Image Preview
+If you click kbd:[mouse-3] on an image link like
+`image⁣:path/to/image[]` the _Image_ context menu pops up.
+
+This context menu allows you to generate or remove the preview for
+the linked image.
+
+The menu item _AsciiDoc → Toggle display of images_ runs the command
+`adoc-toggle-images`. It removes all image previews from the buffer
+if there are any. If there are no image previews in the buffer it
+generates them for all image links.
+
+This may be confusing if all image previews are outside the visible
+region of the buffer. In this case, you might expect `adoc-toggle-images`
+to generate the previews for the image links in the visible area on
+the first run. But it does not, since it first removes all the
+previews, even if you have not seen them.
+
+Just run `adoc-toggle-images` again if it does not what you expect on
+the first run.
 
 == Installation
 
@@ -111,6 +142,15 @@ This can be tweaked by several configuration options:
 * All programming languages `XYZ` that have an Emacs major mode `XYZ-mode` and use `font-lock` are automatically supported. Some other languages not fitting into that name scheme are supported through the alist `adoc-code-lang-modes`. You can add your own languages and modes there if they work based on `font-lock` and are not automatically supported.
 * The fall-back language mode is `prog-mode` without any fontification. You can set your own default by `adoc-fontify-code-block-default-mode`.
 
+=== Display of Image Previews
+
+Images are shown as preview by default when you open an AsciiDoc file.
+You can avoid this by deactivating the option `adoc-display-images`.
+
+The maximal size for the preview of images can be set by `adoc-max-image-size`.
+
+An image link can also be given as url to a remote image. The display of remote images is switched off by default. You can activate it by the option `adoc-display-remote-images`.
+Thereby, images are only downloaded if the protocol of the url matches one of those in the list `adoc-remote-image-protocols`. This list can be customized. By default, it only contains the entry `https`.
 === Syntax Highlighting Customization
 
 It is possible to customize the way `adoc-mode` renders different text