org-screenshot

org-screenshot copied to clipboard

[[http://melpa.org/#/org-attach-screenshot][http://melpa.org/packages/org-attach-screenshot-badge.svg]]

• Overview :PROPERTIES: :ATTACH_DIR: fig :END: org-attach-screenshot allows taking screenshots from within an emacs org buffer session.

  Important note: This package was originally named /org-screenshot/, but due to a name clash with one of the org-contrib packages, I decided to rename it to /org-attach-screenshot/.

  Features:

  • The link to the image file will be placed at /point/

  • /org inline images/ will be turned on to display it.

  • Screenshots are placed into the org entry's attachment directory.

  • If no attachment directory has been defined, the user will be offered choices for creating one or using a directory of an entry higher up in the hierarchy.

  • The emacs frame from which the command is issued will hide away during the screenshot taking, except if a prefix argument has been given (so to allow taking images of the emacs session itself).

    [[file:fig/figure1.png]]

• Installation Put org-attach-screenshot.el into your load-path and the following into your =~/.emacs=:

  #+BEGIN_SRC emacs-lisp (require 'org-attach-screenshot) #+END_SRC

  Or use [[https://github.com/jwiegley/use-package][use-package]]. Here an example which also does some further configuration (see below for the customizable features).

#+BEGIN_SRC emacs-lisp (use-package org-attach-screenshot :bind (" s" . org-attach-screenshot) :config (setq org-attach-screenshot-dirfunction (lambda () (progn (cl-assert (buffer-file-name)) (concat (file-name-sans-extension (buffer-file-name)) "-att"))) org-attach-screenshot-command-line "gnome-screenshot -a -f %f")) #+END_SRC

• Usage While in an org mode buffer, use the org-attach-screenshot command to take a screenshot and have it inserted at the current point.

  If the custom variable org-attach-screenshot-relative-links is non-nil, the links inserted in the org buffer will always be relative to the org document's location. If the variable is set to nil, the links will just be the concatenation of the attachment dir and the filename. So, if absolute path names are desired, you should set this option to nil and make sure that you specify absolute directory names for the attachment directories.

  If =org-attach-screenshot-auto-refresh= is set to =always= the buffers inline images will be automatically refreshed to display every inserted image immediately. Set this to =never= if you prefere to manually refresh inline images. In this case =org-attach-screenshot= will always just insert the link to the image file. Set this to =ask= if you want =org-attach-screenshot= to ask you after every insertion if you would like to refresh the buffer's inline images.

• Configuration ** Customizing the external screenshotting command You can customize the command that is used for taking the screenshot by configuring the =org-attach-screenshot-command-line= variable.

  #+BEGIN_SRC emacs-lisp (setq org-attach-screenshot-command-line "mycommand -x -y -z %f")
  #+END_SRC

  By default the =import= command from the ImageMagick suite is used, i.e. the variable is set to "import %f".

  If your preferred screenshot utility does not allow the passing of a filename as an argument, the suggested solution is to create a small wrapper shell script that provides this functionality. E.g. below is an example shell script that wraps the [[https://flameshot.js.org/#/][flameshot utility]].

  #+BEGIN_SRC bash #!/bin/bash fname="$1" tmpf=$(mktemp -t flshot-XXXX)

  flameshot gui --raw > "$tmpf"

  mv "$tmpf" $1 #+END_SRC

** Customizing the attachment directory name by a function You can also specify a function for generating a directory name, e.g. I often prefer to have the attachment directory names to be linked to the document name, so all screenshots and other material are in a directory that can be conveniently moved together with the main document. You can configure this by setting =org-attach-screenshot-dirfunction= to a function returning the directory name, e.g.

#+BEGIN_SRC emacs-lisp (setq org-attach-screenshot-dirfunction (lambda () (progn (cl-assert (buffer-file-name)) (concat (file-name-sans-extension (buffer-file-name)) "_att")))) #+END_SRC

If =org-attach-screenshot-relative-links= is set to =t= the filename references placed in the org file will be relative filenames. This is probably the best default, since normally you want to be able to move the document together with its attachment directory. If you set this option to =nil= absolute path names will be used.

** Customizing the insertion of links

You may want to customize the way that a screenshot link is inserted. This is possible by setting =org-attach-screenshot-insertfunction= to a function accepting as its single argument the screenshot's filename.

The default function used is =org-attach-screenshot-defaultinsert= #+begin_src emacs-lisp (defun org-attach-screenshot-defaultinsert (linkfilename) "Default function for inserting the image link into the document. The image's filename is passed as the only argument `LINKFILENAME'." (insert (concat "[[file:" linkfilename "]]"))) #+end_src

If you e.g. prefer to have two "\n" characters inserted at the end of the link you may define #+begin_src emacs-lisp (setq org-attach-screenshot-insertfunction (lambda (linkfilename) (insert (concat "[[file:" linkfilename "]]\n\n")) )) #+END_SRC

Naturally, you could put a much fancier function in which e.g. could put a name or caption (using =#+CAPTION:=, etc.) based on some document properties.

• Motivation Org with its Babel functionality is a great tool for producing technical documentation. One can directly use code snippets to produce graphics and have them rendered into the document. So, it is ideal for writing manuals.

  While working on a manual for a graphical application some years ago, I several times had to take screenshots in order to illustrate how to interact with the program. I thought it would be fantastic to have this functionality integrated with org attachments, since this provides a means to associate the figure files with org entries, and not having to copy files around or enter the path information again and again. Also, I wanted to immediately see the results in my org buffer.

  I think that org-attach-screenshot will also be useful for users of the more agenda related features of org mode.

  BTW: There is another nice generic screenshot library available for emacs ([[http://www.emacswiki.org/emacs/screenshot.el][screenshot.el by rubikitch]]) with some great features, but different focus (more generic, allows uploads of screenshots to remote servers and offers multiple predefined storage targets). I used it at first as a dependency of this module, but since I essentially ended up only using the wrapper function for the ImageMagick import command, I decided to rather make it independent instead of forcing users to install both. I wanted to have an especially well integrated screenshot feature to match the org workflow.