#+TITLE: Ement.el

#+PROPERTY: LOGGING nil

Export options.

#+OPTIONS: broken-links:t *:t num:1 toc:1

Info export options.

#+EXPORT_FILE_NAME: ement.texi #+TEXINFO_DIR_CATEGORY: Emacs #+TEXINFO_DIR_TITLE: Ement: (ement) #+TEXINFO_DIR_DESC: Matrix client for Emacs

Note: This readme works with the org-make-toc https://github.com/alphapapa/org-make-toc package, which automatically updates the table of contents.

#+HTML: <img src="images/logo-128px.png" align="right">

ELPA badge image.

[[https://elpa.gnu.org/packages/ement.html][https://elpa.gnu.org/packages/ement.svg]]

Ement.el is a [[http://www.matrix.org/][Matrix]] client for [[https://www.gnu.org/software/emacs/][GNU Emacs]]. It aims to be simple, fast, featureful, and reliable, while integrating naturally with Emacs.

Feel free to join us in the chat room: [[https://matrix.to/#/#ement.el:matrix.org][https://img.shields.io/matrix/ement.el:matrix.org.svg?label=%23ement.el:matrix.org]]

• Contents :noexport: :PROPERTIES: :TOC: :include siblings :END: :CONTENTS:

• [[#installation][Installation]]
• [[#usage][Usage]]
  • [[#bindings][Bindings]]
  • [[#tips][Tips]]
  • [[#encrypted-room-support-through-pantalaimon][Encrypted room support through Pantalaimon]]
• [[#changelog][Changelog]]
• [[#development][Development]] :END:

• Screenshots :noexport: :PROPERTIES: :ID: d818f690-5f22-4eb0-83e1-4d8ce16c9e5b :END:

The default formatting style resembles IRC clients, with each message being prefixed by the username (which enables powerful Emacs features, like using Occur to show all messages from or mentioning a user). Alternative, built-in styles include an Element-like one with usernames above groups of messages, as well as a classic, no-margins IRC style. Messages may be optionally displayed with unique colors for each user (with customizable contrast), making it easier to follow conversations. Timestamp headers are optionally displayed where a certain amount of time passes between events, as well as where the date changes.

[[images/ement-for-twim.png]]

/Two rooms shown in side-by-side buffers, showing inline images, reactions, date/time headings, room avatars, and messages colored by user (using the modus-vivendi Emacs theme)./

[[images/emacs-with-fully-read-line.png]]

/#emacs:libera.chat showing colored text from IRC users, replies with quoted parts, messages colored by user, addressed usernames colored by their user color, highlighted mentions, and the fully-read marker line (using the modus-vivendi Emacs theme)./

[[images/screenshot5.png]]

/Four rooms shown at once, with messages colored by user, in the default Emacs theme./

[[images/screenshot2.png]]

/A room at the top in the "Elemental" display style, with sender names displayed over groups of messages, and only self-messages in an alternate color. The lower window shows an earlier version of the rooms list./

[[images/reactions.png]]

/Reactions displayed as color emojis (may need [[#displaying-symbols-and-emojis][proper Emacs configuration]])./

• Installation :PROPERTIES: :TOC: :depth 0 :END:

** GNU ELPA

Ement.el is published in [[http://elpa.gnu.org/][GNU ELPA]] as [[https://elpa.gnu.org/packages/ement.html][ement]], so it may be installed in Emacs with the command ~M-x package-install RET ement RET~. This is the recommended way to install Ement.el, as it will install the current stable release.

The latest development build may be installed from [[https://elpa.gnu.org/devel/ement.html][ELPA-devel]] or from Git (see below).

** GNU Guix

Ement.el is available in [[https://guix.gnu.org/][GNU Guix]] as [[https://packages.guix.gnu.org/packages/emacs-ement/][emacs-ement]].

** Debian, Ubuntu

Ement.el is available in [[https://packages.debian.org/elpa-ement][Debian as elpa-ement]] and in [[https://packages.ubuntu.com/search?suite=default&section=all&arch=any&keywords=elpa-ement&searchon=names][Ubuntu as elpa-ement]].

** Nix

Ement.el is available in [[https://nixos.org/][NixOS]] as [[https://search.nixos.org/packages?channel=23.05&show=emacsPackages.ement&from=0&size=50&sort=relevance&type=packages&query=ement][emacsPackages.ement]].

** Other distributions

Ement.el is also available in some other distributions. See [[https://repology.org/project/emacs:ement/related][Repology]] for details.

** Git master

The ~master~ branch of the Git repository is intended to be usable at all times; only minor bugs are expected to be found in it before a new stable release is made.

To install, it is recommended to use [[https://github.com/quelpa/quelpa-use-package][quelpa-use-package]], like this (using [[https://github.com/alphapapa/unpackaged.el#upgrade-a-quelpa-use-package-forms-package][this helpful command]] for upgrading versions):

#+BEGIN_SRC elisp ;; Install and load `quelpa-use-package'. (package-install 'quelpa-use-package) (require 'quelpa-use-package)

;; Install Ement. (use-package ement :quelpa (ement :fetcher github :repo "alphapapa/ement.el")) #+END_SRC

One might also use systems like [[https://github.com/progfolio/elpaca][Elpaca]] or [[https://github.com/radian-software/straight.el][Straight]] (which is also used by [[https://github.com/doomemacs/doomemacs][DOOM]]), but the author cannot offer support for them.

** Manual

Ement.el is intended to be installed with Emacs's package system, which will ensure that the required autoloads are generated, etc. If you choose to install it manually, you're on your own.

• Usage :PROPERTIES: :TOC: :include descendants :depth 1 :END: :CONTENTS:

• [[#bindings][Bindings]]
• [[#tips][Tips]]
• [[#encrypted-room-support-through-pantalaimon][Encrypted room support through Pantalaimon]] :END:

1. Call command ~ement-connect~ to connect. Multiple sessions are supported: call the command again with a ~C-u~ universal prefix to connect to another account.
2. Wait for initial sync to complete (which can take a few moments--initial sync JSON responses can be large).
3. Use these commands (room-related commands may be called with universal prefix to prompt for the room):
   • ~ement-list-rooms~ to view the list of joined rooms.
   • ~ement-view-room~ to view a room's buffer, selected with completion.
   • ~ement-create-room~ to create a new room.
   • ~ement-create-space~ to create a space.
   • ~ement-invite-user~ to invite a user to a room.
   • ~ement-join-room~ to join a room.
   • ~ement-leave-room~ to leave a room.
   • ~ement-forget-room~ to forget a room.
   • ~ement-tag-room~ to toggle a tag on a room (including favorite/low-priority status).
   • ~ement-list-members~ to list members in a room.
   • ~ement-send-direct-message~ to send a direct message to a user (in an existing direct room, or creating a new one automatically).
   • ~ement-room-edit-message~ to edit a message at point.
   • ~ement-room-send-file~ to send a file.
   • ~ement-room-send-image~ to send an image.
   • ~ement-room-set-topic~ to set a room's topic.
   • ~ement-room-occur~ to search in a room's known events.
   • ~ement-room-override-name~ to override a room's display name.
   • ~ement-ignore-user~ to ignore a user (or with interactive prefix, un-ignore).
   • ~ement-room-set-message-format~ to set a room's message format buffer-locally.
   • ~ement-room-toggle-space~ to toggle a room's membership in a space (a way to group rooms in Matrix).
   • ~ement-directory~ to view a room directory.
   • ~ement-directory-search~ to search a room directory.
4. Use these special buffers to see events from multiple rooms (you can also reply to messages from these buffers!):
   • See all new events that mention you in the =Ement Mentions= buffer.
   • See all new events in rooms that have open buffers in the =Ement Notifications= buffer.

** Bindings

These bindings are common to all of the following buffer types:

• Switch to a room buffer: ~M-g M-r~
• Switch to the room list buffer: ~M-g M-l~
• Switch to the mentions buffer: ~M-g M-m~
• Switch to the notifications buffer: ~M-g M-n~

*** Room buffers

Note that if global minor mode ~ement-room-self-insert-mode~ is enabled (by default it is disabled), typing any of the common printable ascii characters (such as letters) in a room buffer will start a new message, and most of the following bindings are instead accessed via a prefix key. See the minor mode docstring for details. (The ~?~ binding is an exception; by default it opens the command menu regardless of this minor mode.)

• Show command menu: ~?~

[[images/transient.png]]

Movement

• Next event: ~n~
• Previous event: ~p~
• End of buffer: ~N~
• Scroll up and mark read: ~SPC~
• Scroll down: ~S-SPC~
• Jump to fully-read marker: ~M-g M-p~
• Move read markers to point: ~m~
• Load older messages: at top of buffer, scroll contents up (i.e. ~S-SPC~, ~M-v~ or ~mwheel-scroll~)

Switching

• List rooms: ~M-g M-l~
• Switch to other room: ~M-g M-r~
• Switch to mentions buffer: ~M-g M-m~
• Switch to notifications buffer: ~M-g M-n~
• Quit window: ~q~

Messages

• Write message: ~RET~
• Compose message in buffer: ~M-RET~ (while writing in minibuffer: ~C-c '‍~). Customize the option ~ement-room-compose-method~ to make ~RET~ and the other message bindings use a compose buffer by default. Use command ~ement-room-compose-org~ to activate Org mode in the compose buffer.
• Write reply to event at point: ~S-<return>~
• Edit message: ~<insert>~
• Delete message: ~C-k~
• Send reaction to event at point, or send same reaction at point: ~s r~
• Send emote: ~s e~
• Send file: ~s f~
• Send image: ~s i~
• View event source: ~v~
• Complete members and rooms at point: ~C-M-i~ (standard ~completion-at-point~ command). (Type an ~@~ prefix for a member mention, a ~#~ prefix for a room alias, or a ~!~ prefix for a room ID.)

Images

• Toggle scale of image (between fit-to-window and thumbnail): ~mouse-1~
• Show image in new buffer at full size: ~do