[ANN] Edit emails in Org-mode

[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

Re: [ANN] Edit emails in Org-mode

[Sebastien Vauban]

Hello,

Thorsten Jolitz wrote:
> 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-#                ---

When I have "message" code blocks, and when I edit them in an indirect buffer
(for refilling them, for example), then I have a draft message that stays in
my Gnus/Message emails.

Any idea how to get rid of that?

Best regards,
  Seb

-- 
Sebastien Vauban

Re: [ANN] Edit emails in Org-mode

[Thorsten Jolitz]

"Sebastien Vauban" <sva-news@mygooglest.com>
writes:

Hello, 

its a nice idea to be able to replace the source-blocks by their results when
composing messages (if I understood your feature request right). Opens a lot
of possiblilities for (semi-)automatic email creation.

Here is the doc-string:

#+begin_src emacs-lisp
(defun outorg-replace-source-blocks-with-results
  (&optional arg &rest languages)
  "Replace source-blocks with their results.

Only source-blocks with ':export results' in their header
arguments will be mapped.

If LANGUAGES is non-nil, only those source-blocks with a
language found in the list are mapped.

If LANGUAGES is nil but a prefix-argument ARG is given, only the
languages read from the mini-buffer (separated by blanks) are mapped.

Otherwise, all languages found in `org-babel-load-languages' are mapped." ...)
#+end_src

it basically says:

- only blocks with ':export results' will be mapped

- blocks for all languages found in `org-babel-load-languages' will be mapped,
  except the function ist called (from a program) with a list of language
  names (as strings) or the user calls the command with prefix arg (e.g. C-u)
  and enters language names (like this: R emacs-lisp sh org).

let me know if the function does what you wanted.

Do we need a keybinding for that, or should it rather be a bit oscure (only
accessible by M-x) to avoid confusing accidents?


> Thorsten Jolitz wrote:
>> 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-#                ---
>
> When I have "message" code blocks, and when I edit them in an indirect buffer
> (for refilling them, for example), then I have a draft message that stays in
> my Gnus/Message emails.
>
> Any idea how to get rid of that?
>
> Best regards,
>   Seb

-- 
cheers,
Thorsten

Re: [ANN] Edit emails in Org-mode

[Sebastien Vauban]

HI Thorsten,

Thorsten Jolitz wrote:
> "Sebastien Vauban" <sva-news-D0wtAvR13HarG/iDocfnWg@public.gmane.org> writes:
>> Thorsten Jolitz wrote:
>>> 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-#                ---
>>
>> When I have "message" code blocks, and when I edit them in an indirect buffer
>> (for refilling them, for example), then I have a draft message that stays in
>> my Gnus/Message emails.
>>
>> Any idea how to get rid of that?
>
> its a nice idea to be able to replace the source-blocks by their results
> when composing messages (if I understood your feature request right).

No, this may be a good idea, but not what I was talking about.

I now have the following capture command:

#+begin_src emacs-lisp
  (add-to-list 'org-capture-templates
               `("m" "Mail to task" entry
                 (file+headline ,org-default-notes-file "Tasks")
                 "* TODO %:subject%? (from %:fromname) :mail:
  %:date-timestamp-inactive

#+begin_src message
%i
#+end_src

From %a"
                 :immediate-finish t) t)
#+end_src

But, sometimes, I want to refill the contents of the captured email.

To do so, I go onto the email message code block, edit it in an indirect
buffer (through C-c '), refill, and quit the indirect buffer (another C-c ').

Though, after having done that, I now have the above email saved as a draft in
Gnus. Not what I was expecting.

So, my question was: how to avoid the email to be saved as a draft?

> Opens a lot of possiblilities for (semi-)automatic email creation.
>
> Here is the doc-string:
>
> #+begin_src emacs-lisp
> (defun outorg-replace-source-blocks-with-results
>   (&optional arg &rest languages)
>   "Replace source-blocks with their results.
>
> Only source-blocks with ':export results' in their header
> arguments will be mapped.
>
> If LANGUAGES is non-nil, only those source-blocks with a
> language found in the list are mapped.
>
> If LANGUAGES is nil but a prefix-argument ARG is given, only the
> languages read from the mini-buffer (separated by blanks) are mapped.
>
> Otherwise, all languages found in `org-babel-load-languages' are mapped." ...)
> #+end_src
>
> it basically says:
>
> - only blocks with ':export results' will be mapped
>
> - blocks for all languages found in `org-babel-load-languages' will be mapped,
>   except the function ist called (from a program) with a list of language
>   names (as strings) or the user calls the command with prefix arg (e.g. C-u)
>   and enters language names (like this: R emacs-lisp sh org).
>
> let me know if the function does what you wanted.
>
> Do we need a keybinding for that, or should it rather be a bit oscure (only
> accessible by M-x) to avoid confusing accidents?

Best regards,
  Seb

-- 
Sebastien Vauban

Re: [ANN] Edit emails in Org-mode

[Thorsten Jolitz]

"Sebastien Vauban" <sva-news@mygooglest.com>
writes:

Hi Sebastien,

> Thorsten Jolitz wrote:
>> "Sebastien Vauban" <sva-news@mygooglest.com>
>> writes:
>>> Thorsten Jolitz wrote:
>>>> 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-#                ---
>>>
>>> When I have "message" code blocks, and when I edit them in an
>>> indirect buffer (for refilling them, for example), then I have a
>>> draft message that stays in my Gnus/Message emails.
>>>
>>> Any idea how to get rid of that?
>>
>> its a nice idea to be able to replace the source-blocks by their
>> results when composing messages (if I understood your feature request
>> right).
>
> No, this may be a good idea, but not what I was talking about.

anyway, I really like it for myself ...

> I now have the following capture command:
>
> #+begin_src emacs-lisp
>   (add-to-list 'org-capture-templates
>                `("m" "Mail to task" entry
>                  (file+headline ,org-default-notes-file "Tasks")
>                  "* TODO %:subject%? (from %:fromname) :mail:
>   %:date-timestamp-inactive
>
> #+begin_src message
> %i
> #+end_src
>
> From %a"
>                  :immediate-finish t) t)
> #+end_src
>
> But, sometimes, I want to refill the contents of the captured email.
>
> To do so, I go onto the email message code block, edit it in an indirect
> buffer (through C-c '), refill, and quit the indirect buffer (another C-c ').
>
> Though, after having done that, I now have the above email saved as a draft in
> Gnus. Not what I was expecting.
>
> So, my question was: how to avoid the email to be saved as a draft?

Thats quite a complicated set-up, not sure if I really can say something
about that.

Maybe you noticed, that in my original post I exported my mail written in the
*outorg-edit-buffer* to ASCII with this code 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

and the result looked like this (I did not fiddle with the export options,
just used the settings I have):

#+results:

,----------------------------------------------
| "                           _________________
|
|                                   134
|
|                             Thorsten Jolitz
|                            _________________
|
|
| Table of Contents
| _________________
|
| 1 --text follows this line--
| 2 Documentation
`----------------------------------------------

I think this 134 in the headline comes from Gnus too, and is a draft number or
so. I'm not really sure whats happening there, it seems to be something
between Org and Gnus. I do use C-c ' in the *outorg-edit-buffer* too for
editing source-blocks, not sure if Org-mode automatically saves the original
buffer when returning from the temporal (source-code) edit buffer and updating
the original buffer - but that would then be the *outorg-edit-buffer*, not
the message-buffer.

I checked outorg.el - there is only one explicit use of 'save-buffer' not
related to this, so I don't seem to save the original-buffer when returning
from *outorg-edit-buffer* buffer (and I remember that I decided to better
leave that to the user).

>> Opens a lot of possiblilities for (semi-)automatic email creation.
>>
>> Here is the doc-string:
>>
>> #+begin_src emacs-lisp
>> (defun outorg-replace-source-blocks-with-results
>>   (&optional arg &rest languages)
>>   "Replace source-blocks with their results.
>>
>> Only source-blocks with ':export results' in their header
>> arguments will be mapped.
>>
>> If LANGUAGES is non-nil, only those source-blocks with a
>> language found in the list are mapped.
>>
>> If LANGUAGES is nil but a prefix-argument ARG is given, only the
>> languages read from the mini-buffer (separated by blanks) are mapped.
>>
>> Otherwise, all languages found in `org-babel-load-languages' are mapped." ...)
>> #+end_src
>>
>> it basically says:
>>
>> - only blocks with ':export results' will be mapped
>>
>> - blocks for all languages found in `org-babel-load-languages' will be mapped,
>>   except the function ist called (from a program) with a list of language
>>   names (as strings) or the user calls the command with prefix arg (e.g. C-u)
>>   and enters language names (like this: R emacs-lisp sh org).
>>
>> let me know if the function does what you wanted.
>>
>> Do we need a keybinding for that, or should it rather be a bit oscure (only
>> accessible by M-x) to avoid confusing accidents?
>
> Best regards,
>   Seb

--
cheers,
Thorsten