[O] [ANN] Edit emails in Org-mode

[Thorsten Jolitz]

Hi List,

it is now possible to edit your emails in (full!) Org-mode (assuming you
write them in `message-mode' as Gnus users do).

* Documentation
** Downloads

You need two libraries for this (the optional third library `navi-mode' is
not needed here, but in general very useful in combination with the other two
libraries or Org-mode).

- [[https://github.com/tj64/outshine][outshine.el]]
- [[https://github.com/tj64/outorg][outorg.el]]

Download them or clone the github repos and make sure Emacs finds them.

** Installation

Put this in your '.emacs' file:

#+begin_src emacs-lisp
  ;; If you want a different prefix key for outline-minor-mode, insert first:
  ;; (defvar outline-minor-mode-prefix "\C-c") or whatever. The prefix can only
  ;; be changed before outline (minor) mode is loaded. "\C-c" unfortunately
  ;; conflicts with other modes, e.g. ESS and picolisp-wiki-mode.
  (defvar outline-minor-mode-prefix "\M-#")

  (require 'outline)
  (require 'outshine)

  (add-hook 'outline-minor-mode-hook 'outshine-hook-function)
  (add-hook 'message-mode-hook 'outline-minor-mode)

  (require 'outorg)
  ;; optional (require 'navi)

#+end_src

Note that

#+begin_src emacs-lisp
  (add-hook 'emacs-lisp-hook 'outline-minor-mode)
#+end_src

is very useful too, though not necessary in this case.

In fact, `outline-minor-mode' extended by the library-trio /outline.el/,
/outorg.el/ and /navi-mode.el/ should work in all kinds of Emacs major-modes
(at least in theory) when files are structured 'the outshine way', i.e. with
outcommented Org-mode headlines (e.g. "^;; [*]+ "). Emacs Lisp files with
conventional headers ("^;;;+ ") are a special case, they work too.

It has been tested with emacs-lisp-mode, picolisp-mode, R-mode, sql-mode,
latex-mode and maybe others I'm not aware of).

** Usage

There are only two commands involved:

| Command                        | Keybinding        | Comment            |
|--------------------------------+-------------------+--------------------|
| M-x outorg-edit-as-org         | M-# M-#  or M-# # | outline-prefix M-# |
|                                | C-c '             | outline-prefix C-c |
| M-x outorg-copy-edits-and-exit | M-#               | ---                |

Call `outorg-edit-as-org' in the message-buffer, and the text part of the
unsent email if offered for editing in a temporary Org-mode buffer.

Call `outorg-copy-edits-and-exit' when you are done with editing, and the
content of the temporary edit buffer is copied into the message-mode buffer.

The temporary edit buffer *outorg-edit-buffer* is saved in the /tmp directory
when accidentally killed, so no edits can be lost. You can save the buffer to
its backup file whenever you want with the usual 'C-x C-s'.

*NOTE*
`outorg-edit-as-org' normally acts on the subtree at point, but thats no
problem for the use with `message-mode', except in one situation: When the
message-mode buffer already contains body-text, and this text contains
Org-mode style headlines ("^[*]+ "), then these headlines will be
interpretated by outorg as subtrees during the buffer preparation phase, thus
`outorg-edit-as-org' will act only on the first subtree.

 In this case, simply call `outorg-edit-as-org' with prefix, e.g. 'C-u M-#
M-#', then the whole mail body will be offered for editing in Org-mode.

** Alternatives

You can use `orgstruct-minor-mode' to make a subset of Org-mode's
functionality available in `message-mode'. The extra-cost of using the
combination of `outshine' and `outorg' instead is typing once 'M-# M-#' and
once 'M-#', the extra-benefit is the *full* power of Org-mode at your
fingertips when writing emails.

** Read more

There is an article on
[[http://orgmode.org/worg/org-tutorials/org-outside-org.html][Worg]]
about the libraries described in this post.

** Example

This email has be written in the *outorg-edit-buffer*, so I can do some stuff
not necessarily associated with writing email. Lets export this mail to ASCII
and attach the result below - without leaving this buffer of course (except
for editing the source-block), just by doing 'C-c C-c' inside the block:

#+begin_src emacs-lisp :results output replace
  (org-export-to-buffer 'ascii "email-transcode-buffer")
  (print
   (with-current-buffer "email-transcode-buffer"
     (let ((mail-as-ascii
            (buffer-substring-no-properties (point-min) (point-max))))
       (set-buffer-modified-p nil)
       (kill-buffer)
       mail-as-ascii)))
#+end_src

#+results:

"                           _________________

                                  134

                            Thorsten Jolitz
                           _________________


Table of Contents
_________________

1 --text follows this line--
2 Documentation
.. 2.1 Downloads
.. 2.2 Installation
.. 2.3 Usage
.. 2.4 Alternatives
.. 2.5 Read more
.. 2.6 Example


1 --text follows this line--
============================

  Hi List,

  it is now possible to edit your emails in (full!) Org-mode (assuming
  you write them in `message-mode' as Gnus users do).


2 Documentation
===============

2.1 Downloads
~~~~~~~~~~~~~

  You need two libraries for this (the optional third library
  `navi-mode' is not needed here, but in general very useful in
  combination with the other two libraries or Org-mode).

  - [outshine.el]
  - [outorg.el]

  Download them or clone the github repos and make sure Emacs finds
  them.


  [outshine.el] https://github.com/tj64/outshine

  [outorg.el] https://github.com/tj64/outorg


2.2 Installation
~~~~~~~~~~~~~~~~

  Put this in your '.emacs' file:

  ,----
  | ;; If you want a different prefix key for outline-minor-mode, insert first:
  | ;; (defvar outline-minor-mode-prefix \"\\C-c\") or whatever. The prefix can 
only
  | ;; be changed before outline (minor) mode is loaded. \"\\C-c\" unfortunately
  | ;; conflicts with other modes, e.g. ESS and picolisp-wiki-mode.
  | (defvar outline-minor-mode-prefix \"\\M-#\")
  |
  | (require 'outline)
  | (require 'outshine)
  |
  | (add-hook 'outline-minor-mode-hook 'outshine-hook-function)
  | (add-hook 'message-mode-hook 'outline-minor-mode)
  |
  | (require 'outorg)
  | ;; optional (require 'navi)
  `----

  Note that

  ,----
  | (add-hook 'emacs-lisp-hook 'outline-minor-mode)
  `----

  is very useful too, though not necessary in this case.

  In fact, `outline-minor-mode' extended by the library-trio
  /outline.el/, /outorg.el/ and /navi-mode.el/ should work in all kinds
  of Emacs major-modes (at least in theory) when files are structured
  'the outshine way', i.e. with outcommented Org-mode headlines (e.g.
  \"^;; [*]+ \"). Emacs Lisp files with conventional headers (\"^;;;+ \")
  are a special case, they work too.

  It has been tested with emacs-lisp-mode, picolisp-mode, R-mode,
  sql-mode, latex-mode and maybe others I'm not aware of).


2.3 Usage
~~~~~~~~~

  There are only two commands involved:

   Command                         Keybinding         Comment
  -----------------------------------------------------------------------
   M-x outorg-edit-as-org          M-# M-#  or M-# #  outline-prefix M-#
                                   C-c '              outline-prefix C-c
   M-x outorg-copy-edits-and-exit  M-#                ---

  Call `outorg-edit-as-org' in the message-buffer, and the text part of
  the unsent email if offered for editing in a temporary Org-mode
  buffer.

  Call `outorg-copy-edits-and-exit' when you are done with editing, and
  the content of the temporary edit buffer is copied into the
  message-mode buffer.

  The temporary edit buffer *outorg-edit-buffer* is saved in the /tmp
  directory when accidentally killed, so no edits can be lost. You can
  save the buffer to its backup file whenever you want with the usual
  'C-x C-s'.

  *NOTE* `outorg-edit-as-org' normally acts on the subtree at point, but
  thats no problem for the use with `message-mode', except in one
  situation: When the message-mode buffer already contains body-text,
  and this text contains Org-mode style headlines (\"^[*]+ \"), then these
  headlines will be interpretated by outorg as subtrees during the
  buffer preparation phase, thus `outorg-edit-as-org' will act only on
  the first subtree.

   In this case, simply call `outorg-edit-as-org' with prefix, e.g. 'C-u
  M-# M-#', then the whole mail body will be offered for editing in
  Org-mode.


2.4 Alternatives
~~~~~~~~~~~~~~~~

  You can use `orgstruct-minor-mode' to make a subset of Org-mode's
  functionality available in `message-mode'. The extra-cost of using the
  combination of `outshine' and `outorg' instead is typing once 'M-#
  M-#' and once 'M-#', the extra-benefit is the *full* power of Org-mode
  at your fingertips when writing emails.


2.5 Read more
~~~~~~~~~~~~~

  There is an article on [Worg] about the libraries described in this
  post.


  [Worg] http://orgmode.org/worg/org-tutorials/org-outside-org.html


2.6 Example
~~~~~~~~~~~

  This email has be written in the *outorg-edit-buffer*, so I can do
  some stuff not necessarily associated with writing email. Lets export
  this mail to ASCII and attach the result below - without leaving this
  buffer of course (except for editing the source-block), just by doing
  'C-c C-c' inside the block:

  ,----
  | (org-export-to-buffer 'ascii \"email-transcode-buffer\")
  | (print
  |  (with-current-buffer \"email-transcode-buffer\"
  |    (let ((mail-as-ascii
  |           (buffer-substring-no-properties (point-min) (point-max))))
  |      (set-buffer-modified-p nil)
  |      (kill-buffer)
  |      mail-as-ascii)))
  `----

  -- cheers, Thorsten
"

--
cheers,
Thorsten