Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/jeremy-compostella/org-msg

OrgMsg is a GNU/Emacs global minor mode mixing up Org mode and Message mode to compose and reply to emails in a Outlook HTML friendly style.
https://github.com/jeremy-compostella/org-msg

composing emacs emacs-mode emacs-packages html mail org-mode orgmode outlook

Last synced: 3 months ago
JSON representation

OrgMsg is a GNU/Emacs global minor mode mixing up Org mode and Message mode to compose and reply to emails in a Outlook HTML friendly style.

Awesome Lists containing this project

README 

        
*OrgMsg* is a [[https://www.gnu.org/software/emacs/][GNU Emacs]] global minor mode mixing up [[https://orgmode.org/][Org mode]] and your Mail User Agent Mode ([[https://www.gnu.org/software/emacs/manual/html_mono/message.html][Message mode]], [[https://www.djcbsoftware.nl/code/mu/mu4e/][mu4e mode]], or [[https://notmuchmail.org/notmuch-emacs/][notmuch mode]]) to compose and reply to emails in a Outlook HTML friendly style.



[[https://melpa.org/#/org-msg][https://melpa.org/packages/org-msg-badge.svg]] [[https://img.shields.io/badge/License-GPLv3-blue.svg]]



* Presentation



Not that I really like the Outlook email style but in a work environment dominated by this email client, it is good to be able to reply with the same style.  By default, if the original message is in plain text *OrgMsg* keeps it that way and does not activate itself.  It allows to reply to developer mailing list (or any real technical people who knows how to handle text email) seamlessly. This behavior can customized as documented in the [[README.org#Configuration][Configuration]] section below. If the original message is in the HTML form, it activates the *OrgMsg* mode on the reply buffer.



*OrgMsg* provides a ~org-msg-edit-mode~ which is an derivation of [[https://orgmode.org/][Org mode]] in which some functionality of the current Mail User Agent ([[https://www.gnu.org/software/emacs/manual/html_mono/message.html][Message mode]], [[https://www.djcbsoftware.nl/code/mu/mu4e/][mu4e mode]], or [[https://notmuchmail.org/notmuch-emacs/][notmuch mode]]) are imported or replicated. For instance, a *OrgMsg* buffer uses the same ~font-lock-keywords~ than [[https://www.gnu.org/software/emacs/manual/html_mono/message.html][Message mode]] or the ~TAB~ key while the cursor is in the header calls the ~message-tab~ function.



For convenience, the original message is quoted below the ~--citation follows this line (read-only)--~ marker.  So you can easily refer to the original message.  However, the entire quoted text is read-only because *OrgMsg* does not support modification of the original content.



*OrgMsg* has a mechanism to support different Mail User Agents (message, mu4e, notmuch ...).  Each function which depends on the Mail User Agent calls ~org-msg-mua-call~ function which is an indirection to the OrgMsg Mail User Agent specific function.



Outlook email are really poor compared to what can be achieved by [[https://orgmode.org/][Org mode]].  I personally use the ~#+{begin|end}_quote~ to quote part of the email I am replying to.  I extensively make use of ~#+{begin|end}_src mode~ to provide extract of code or example of changes, I sometimes use [[https://orgmode.org/worg/org-contrib/babel/][Org babel]] to generate an on the fly sequence diagram (using [[http://plantuml.com/][plantuml]]) or a simple graph (using [[https://en.wikipedia.org/wiki/DOT_(graph_description_language)][dot]]).



* Keys and interactive functions



The *OrgMsg* mode keys are the usual key combination used in either [[https://orgmode.org/][Org mode]] or [[https://www.gnu.org/software/emacs/manual/html_mono/message.html][Message mode]].



- ~C-c C-e~ -- calls ~org-msg-preview~ which generate and display the exported version of the email

- ~C-c C-k~ -- calls ~message-kill-buffer~

- ~C-c C-s~ -- calls ~message-goto-subject~ (same as in [[https://www.gnu.org/software/emacs/manual/html_mono/message.html][Message mode]])

- ~C-c C-b~ -- calls ~org-msg-goto-body~ (similar to ~message-goto-body~ in [[https://www.gnu.org/software/emacs/manual/html_mono/message.html][Message mode]])

- ~C-c C-a~ -- calls ~org-msg-attach~, very similar to the ~org-attach~ function.  It lets you add or delete attachment for this email.  Attachment list is stored in the ~:attachment:~ property.

- ~C-c C-c~ -- calls ~org-ctrl-c-ctrl-c~. *OrgMsg* configures ~org-msg-ctrl-c-ctrl-c~ as a final hook of [[https://orgmode.org/][Org mode]]. When ~org-msg-ctrl-c-ctrl-c~ is called in a *OrgMsg* buffer it generates the MIME message, sends it and exits. If the universal argument is supplied, the last step is skipped.



The ~org-msg-mode~ interactive function can be called to enable/disable *OrgMsg*.  By default, once the module is loaded, it is disable.  If you want to reply to an email without making use of *OrgMsg*, you should call that function before you call the reply-to function.



To start composing a new *OrgMsg* email, you can call the interactive ~message-mail~ function.  If your ~mail-user-agent~ is ~message-user-agent~ (which is the by default Emacs configuration), ~compose-mail~ calls ~message-mail~ and is bound to ~[C-x m]~ by default.



* Configuration



*OrgMsg* depends on this module: [[https://github.com/hniksic/emacs-htmlize][emacs-htmlize]]



The default Emacs Mail User Agent is [[https://www.gnu.org/software/emacs/manual/html_mono/message.html][Message]], if you are a  [[https://www.djcbsoftware.nl/code/mu/mu4e/][mu4e]] user, you need to define your mail user agent (see [[https://www.djcbsoftware.nl/code/mu/mu4e/Emacs-default.html#Emacs-default][mu4e documentation - Emacs-default]]) because  *OrgMsg* places some hooks and runs specific functions depending on the current Mail User Agent. The proper Mail User Agent should be defined before you activate *OrgMsg* (call the ~org-msg-mode~ function). Here is how you can define the Mail User Agent [[https://www.djcbsoftware.nl/code/mu/mu4e/][mu4e]].



#+begin_src emacs-lisp

(setq mail-user-agent 'mu4e-user-agent)

#+end_src



The following is my configuration which you can use as an example.



#+begin_src emacs-lisp

  (setq mail-user-agent 'gnus-user-agent)

  (require 'org-msg)

  (setq org-msg-options "html-postamble:nil H:5 num:nil ^:{} toc:nil author:nil email:nil \\n:t"

	org-msg-startup "hidestars indent inlineimages"

	org-msg-greeting-fmt "\nHi%s,\n\n"

	org-msg-recipient-names '(("[email protected]" . "Jérémy"))

	org-msg-greeting-name-limit 3

	org-msg-default-alternatives '((new		. (text html))

				       (reply-to-html	. (text html))

				       (reply-to-text	. (text)))

	org-msg-convert-citation t

	org-msg-signature "



  Regards,



  ,#+begin_signature

  --

  ,*Jeremy*

  /One Emacs to rule them all/

  ,#+end_signature")

  (org-msg-mode)

#+end_src



The ~org-msg-greeting-fmt~ can be customized to configure the default greeting message.  If this format contains a ~%s~ token it is automatically replaced with the name of the person you are replying to with a space prefix.  The name is either the recipient name specified in the ~org-msg-recipient-names~ list or the first name automatically extracted from the email address. If ~org-msg-greeting-fmt-mailto~ is t, the name is formatted as mailto link.



The types of MIME alternatives that are sent can be modified by editing the ~:alternatives:~ property on each message. For example, setting this property to ~(text html)~ will send both text and HTML alternatives to your message, whereas ~(html)~ or ~(text)~ will just send HTML or plain text respectively.



The default value of the ~:alternatives:~ property can be set with the

~org-msg-default-alternatives~ customization variable. It is associative list which value is a list of alternatives and the key is one of the following:

- ~new~ for a new email

- ~reply-to-html~ for a reply to an HTML email

- ~reply-to-text~ for a reply to a plain text email

If one of these keys is not present *OrgMsg* does not activate for this type of email.



If you want to add your own custom exporters, this can be done by modifying ~org-msg-alternative-exporters~.



Alternatives list should be placed in increasing order of preference to meet [[https://www.w3.org/Protocols/rfc1341/7_2_Multipart.html][RFC-1341]] *section 7.2.3* guidelines.



*OrgMsg* composes reply to HTML emails in [[https://en.wikipedia.org/wiki/Posting_style#Top-posting][top-posting]] style. This behavior can be disabled by setting ~org-msg-posting-style~ to any value other than ~top-posting~.



The original HTML message generated by gnus includes fields such as ~From~ and ~To~. Unfortunately, some less desirable field like ~attachment~ are sometimes added. These fields can be listed in ~org-msg-undesirable-headers~ to be automatically removed by *OrgMsg*.



In order to avoid CSS conflict, *OrgMsg* performs inline replacement when it generates the final HTML message.  See the ~org-msg-enforce-css~ variable to customize the style (and the default ~org-msg-default-style~ variable for reference).



Setting the org export option ~tex:dvipng~ or ~tex:dvisvgm~ is handeled correctly by this mode by producing inline images or inlining the generated SVG. Note that most mailclients however sadly do not display SVG content in mails so it might be best to stick to settings producing images unless you know your recipient's mailclient supports SVG.



*OrgMsg* includes a minimalist detection of missing attachment which relies on a regular expression defined by the ~org-msg-attached-file-reference~ customization variable.



** Advanced configuration



It would be impossible for *OrgMsg* to offer composition customization variables to accommodate all the combinations of desirable behaviors. For instance, one could want to reply as plain text only for a certain type of email as characterized by the sender domain name or a subject prefix. Or another could want to change its signature when replying as plain text only. In addition, emails can be used to interact with machines and their protocol can have even more exotic requirements.



To offer plenty of flexibility without turning *OrgMsg* into an unsustainable project, *OrgMsg* implements the two following and well documented functions. They are called at composition time by the ~org-msg-post-setup~ function with the new message as the current buffer. They can be advised by the end-user to implement any particular behavior (cf. [[https://www.gnu.org/software/emacs/manual/html_node/elisp/Advising-Functions.html][Advising Emacs Lisp Functions]]).

- ~org-msg-get-alternatives(type)~ returns the list of alternatives

- ~org-msg-composition-parameters (type alternatives)~ returns the posting style, greeting format and signature



For example, here is how I configure *OrgMsg* to dynamically change my greeting message and signature when I reply as a plain text.



#+begin_src emacs-lisp

  (defun my-org-msg-composition-parameters (orig-fun &rest args)

    "Tweak my greeting message and my signature when replying as

    plain/text only."

    (let ((res (apply orig-fun args)))

      (when (equal (cadr args) '(text))

	(setf (alist-get 'greeting-fmt res) "\n")

	(setf (alist-get 'signature res)

	      (replace-regexp-in-string "\\([\*/]\\|\nRegards,\n\n\\)" ""

					org-msg-signature)))

      res))

  (advice-add 'org-msg-composition-parameters

	      :around #'my-org-msg-composition-parameters)

#+end_src



* Quotes



Org mode supports quotes using [[https://www.gnu.org/software/emacs/manual/html_mono/org.html#Paragraphs][quote blocks]]. The Org mode HTML backend exports such blocks as ~blockquote~ HTML tags and *OrgMsg* will apply a CSS style on top of it.  Unfortunately, the Org mode engine does not allow nested quote blocks.



*OrgMsg* supports nested quotes with special ~#+{begin|end}_quote[0-9]+~ blocks. A ~#+{begin|end}_quote1~ block can be nested in a ~#+{begin|end}_quote~ block, a  ~#+{begin|end}_quote2~ block can be nested in a ~#+{begin|end}_quote1~ block ... In order to ease the identification of the different levels of quotes once exported to HTML, each level uses a different color.



Using ~#+{begin|end}_quote[0-9]+~ can be cumbersome and as thus, *OrgMsg*  also supports the automatic conversion of the well established ASCII quote form based on the ~>~ characters. For instance, if the ~org-msg-convert-citation~ customization variable is set to ~t~, the following text will be automatically converted to multi-level quote blocks before being exported to HTML.



#+begin_src

> quote an email

>> which had quoted another email

>>> which had quoted another email

#+end_src



And it will look like this.



[[./quotes.png]]