\input texinfo    @c -*- texinfo -*-
@c %**start of header
@setfilename mastodon.info
@settitle 
@documentencoding UTF-8
@documentlanguage en
@c %**end of header

@dircategory Emacs
@direntry
* Mastodon: (mastodon). Client for Mastodon on ActivityPub networks.
@end direntry

@finalout
@titlepage
@title 
@end titlepage

@contents

@ifnottex
@node Top
@top 
@end ifnottex

@menu
* README::

@detailmenu
--- The Detailed Node Listing ---

README

* Installation::
* Usage::
* Dependencies::
* Network compatibility::
* Contributing::
* Supporting @samp{mastodon.el}: Supporting @samp{mastodonel}. 
* Contributors::
* screenshots::

Installation

* ELPA::
* MELPA::
* Repo::
* Emoji::
* Discover::

Usage

* Logging in to your instance::
* Timelines::
* Composing toots::
* Other commands and account settings::
* Customization::
* Commands and variables index::
* Alternative timeline layout::
* Live-updating timelines @samp{mastodon-async-mode}::
* Translating toots::
* Bookmarks and @samp{mastodon.el}: Bookmarks and @samp{mastodonel}. 

Contributing

* Bug reports::
* Fixes and features::
* Coding style::

@end detailmenu
@end menu

@node README
@chapter README

@samp{mastodon.el} is an Emacs client for the AcitivityPub social networks that
implement the Mastodon API@. For info see @uref{https://joinmastodon.org/, joinmastodon.org}.

NB: @samp{mastodon.el} now ships this readme as an .info file, so if you have it installed you should be able to browse this readme inside emacs. @samp{C-h i} for info, then @samp{m masto RET} should load it for you.

@menu
* Installation::
* Usage::
* Dependencies::
* Network compatibility::
* Contributing::
* Supporting @samp{mastodon.el}: Supporting @samp{mastodonel}. 
* Contributors::
* screenshots::
@end menu

@node Installation
@section Installation

You can install @samp{mastodon.el} from ELPA, MELPA, or directly from this repo. It is also available as a GUIX package.

@menu
* ELPA::
* MELPA::
* Repo::
* Emoji::
* Discover::
@end menu

@node ELPA
@subsection ELPA

You should be able to directly install with:

@samp{M-x package-refresh-contents RET}

@samp{M-x package-install RET mastodon RET}

@node MELPA
@subsection MELPA

Add @samp{MELPA} to your archives:

@lisp
(require 'package)
(add-to-list 'package-archives
             '("melpa" . "http://melpa.org/packages/") t)
@end lisp

Update and install:

@samp{M-x package-refresh-contents RET}

@samp{M-x package-install RET mastodon RET}

@node Repo
@subsection Repo

Clone this repository and add the lisp directory to your load path.
Then, require it and go.

@lisp
(add-to-list 'load-path "/path/to/mastodon.el/lisp")
(require 'mastodon)
@end lisp

Or, with @samp{use-package}:

@lisp
(use-package mastodon
  :ensure t)
@end lisp

The minimum Emacs version is now 27.1. But if you are running an older version
it shouldn't be very hard to get it working.

@node Emoji
@subsection Emoji

Since Emacs 28, it has builtin emoji support with @samp{emoji.el}. If you prefer to use @uref{https://github.com/iqbalansari/emacs-emojify, Emojify}, @samp{require} it and set @samp{mastodon-use-emojify} to non-nil to display emoji in timelines and to use it when composing toots. @samp{Emoji.el} is the better option, but for now only @samp{emojify} supports downloading and using custom emoji from your instance.

@node Discover
@subsection Discover

@samp{mastodon-mode} can provide a context menu for its keybindings if @uref{https://github.com/mickeynp/discover.el, Discover} is
installed. It is not required.

if you have Discover, add the following to your Emacs init configuration:

@lisp
(require 'mastodon-discover)
(with-eval-after-load 'mastodon (mastodon-discover))
@end lisp

Or, with @samp{use-package}:

@lisp
(use-package mastodon
  :ensure t
  :config
  (mastodon-discover))
@end lisp

@node Usage
@section Usage

@menu
* Logging in to your instance::
* Timelines::
* Composing toots::
* Other commands and account settings::
* Customization::
* Commands and variables index::
* Alternative timeline layout::
* Live-updating timelines @samp{mastodon-async-mode}::
* Translating toots::
* Bookmarks and @samp{mastodon.el}: Bookmarks and @samp{mastodonel}. 
@end menu

@node Logging in to your instance
@subsection Logging in to your instance

You need to set 2 variables in your init file to get started:

@enumerate
@item
@samp{mastodon-instance-url}
@item
@samp{mastodon-active-user}
@end enumerate

(see their doc strings for details). For example If you want to post
toots as "example@math{_user}@@social.instance.org", then put this in your init
file:

@lisp
(setq mastodon-instance-url "https://social.instance.org"
      mastodon-active-user "example_user")
@end lisp

Then @strong{restart} Emacs and run @samp{M-x mastodon}. Make sure you are connected
to internet before you do this. If you have multiple mastodon accounts
you can activate one at a time by changing those two variables and
restarting Emacs.

If you were using mastodon.el before 2FA was implemented and the above steps
do not work, delete the old file specified by @samp{mastodon-client--token-file} and
restart Emacs and follow the steps again.

@node Timelines
@subsection Timelines

@samp{M-x mastodon}

Opens a @samp{*mastodon-home*} buffer in the major mode and displays toots. If your
credentials are not yet saved, you will be prompted for email and password.
The app registration process will take place if your @samp{mastodon-token-file} does
not contain @samp{:client_id} and @samp{:client_secret}.

@enumerate
@item
@anchor{Keybindings}Keybindings


For a full list of commands and variables, see @uref{mastodon-index.org, mastodon-index.org}.

@multitable {aaaaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
@headitem Key
@tab Action
@item 
@tab @strong{Help}
@item @samp{?}
@tab Show discover menu of all bindings, if @samp{discover} is available
@item 
@tab @strong{Timeline actions}
@item @samp{n}
@tab Go to next item (toot, notification, user)
@item @samp{p}
@tab Go to previous item (toot, notification, user)
@item @samp{M-n=/=<tab>}
@tab Go to the next interesting thing that has an action
@item @samp{M-p=/=<S-tab>}
@tab Go to the previous interesting thing that has an action
@item @samp{F}
@tab Open federated timeline (1 prefix arg: hide-replies, 2 prefix args: media only)
@item @samp{H}
@tab Open home timeline  (1 prefix arg: hide-replies)
@item @samp{L}
@tab Open local timeline (1 prefix arg: hide-replies, 2 prefix args: media only)
@item @samp{N}
@tab Open notifications timeline
@item @samp{@@}
@tab Open mentions-only notifications timeline
@item @samp{u}
@tab Update current timeline
@item @samp{T}
@tab Open thread for toot at point
@item @samp{#}
@tab Prompt for tag and open its timeline
@item @samp{A}
@tab Open author profile of toot at point
@item @samp{P}
@tab Open profile of user attached to toot at point
@item @samp{O}
@tab View own profile
@item @samp{U}
@tab update your profile bio note
@item @samp{;}
@tab view instance description for toot at point
@item @samp{:}
@tab view followed tags and load a tag timeline
@item @samp{C-:}
@tab view timeline of all followed tags
@item @samp{,}
@tab view favouriters of toot at point
@item @samp{.}
@tab view boosters of toot at point
@item @samp{/}
@tab switch between mastodon buffers
@item @samp{\}
@tab prompt for an instance domain and view its local timeline (if poss)
@item @samp{Z}
@tab report user/toot at point to instances moderators
@item 
@tab @strong{Other views}
@item @samp{s}
@tab search (posts, users, tags) (NB: only posts you have interacted with)
@item @samp{I}, @samp{c}, @samp{d}
@tab view, create, and delete filters
@item @samp{R}, @samp{a}, @samp{j}
@tab view/accept/reject follow requests
@item @samp{G}
@tab view follow suggestions
@item @samp{V}
@tab view your favourited toots
@item @samp{K}
@tab view bookmarked toots
@item @samp{X}
@tab view/edit/create/delete lists
@item @samp{S}
@tab view your scheduled toots
@item 
@tab @strong{Toot actions}
@item @samp{t}
@tab Compose a new toot
@item @samp{c}
@tab Toggle content warning content
@item @samp{b}
@tab Boost toot under @samp{point}
@item @samp{f}
@tab Favourite toot under @samp{point}
@item @samp{k}
@tab toggle bookmark of toot at point
@item @samp{r}
@tab Reply to toot under @samp{point}
@item @samp{v}
@tab Vote on poll at point
@item @samp{C}
@tab copy url of toot at point
@item @samp{C-RET}
@tab play video/gif at point (requires @samp{mpv})
@item @samp{e}
@tab edit your toot at point
@item @samp{E}
@tab view edits of toot at point
@item @samp{i}
@tab (un)pin your toot at point
@item @samp{d}
@tab delete your toot at point, and reload current timeline
@item @samp{D}
@tab delete and redraft toot at point, preserving reply/CW/visibility
@item (@samp{S-C-}) @samp{W}, @samp{M}, @samp{B}
@tab (un)follow, (un)mute, (un)block author of toot at point
@item 
@tab @strong{Profile view}
@item @samp{C-c C-c}
@tab cycle between statuses, statuses without boosts, followers, and following
@item 
@tab @samp{mastodon-profile--account-account-to-list} (see lists view)
@item 
@tab @strong{Notifications view}
@item @samp{a}, @samp{j}
@tab accept/reject follow request
@item @samp{C-k}
@tab clear notification at point
@item 
@tab see @samp{mastodon-notifications--get-*} functions for filtered views
@item 
@tab @strong{Quitting}
@item @samp{q}
@tab Quit mastodon buffer, leave window open
@item @samp{Q}
@tab Quit mastodon buffer and kill window
@item @samp{C-M-q}
@tab Quit and kill all mastodon buffers
@end multitable

@item
@anchor{Toot byline legend}Toot byline legend


@multitable {aaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaa}
@headitem Marker
@tab Meaning
@item @samp{(🔁)} (or @samp{(B)})
@tab I boosted this toot
@item @samp{(⭐)} (or @samp{(F)})
@tab I favourited this toot
@item @samp{(🔖)} (or (@samp{K}))
@tab I bookmarked this toot
@end multitable
@end enumerate

@node Composing toots
@subsection Composing toots

@samp{M-x mastodon-toot} (or @samp{t} from a mastodon.el buffer) opens a new buffer/window
in @samp{text-mode} and @samp{mastodon-toot} minor mode. Enter the contents of your toot
here. @samp{C-c C-c} sends the toot. @samp{C-c C-k} cancels. Both actions kill the buffer
and window. Further keybindings are displayed in the buffer, and in the following subsection.

Replies preserve visibility status/content warnings, and include boosters by default. If the region is active when you start a reply, it will be yanked into the compose buffer prefixed with @samp{>} to form a rough reply quote.

Server's max toot length, with running char count, and attachment previews, are shown.

You can download and use your instance's custom emoji
(@samp{mastodon-toot--download-custom-emoji}, @samp{mastodon-toot--enable-custom-emoji}).

If you want to view some of the toot being replied to in the compose buffer, set @samp{mastodon-toot-display-orig-in-reply-buffer} to non-nil.

The compose buffer uses @samp{text-mode} so any configuration you have for that mode
will be enabled. If any of your existing config conflicts with @samp{mastodon-toot},
you can disable it in the @samp{mastodon-toot-mode-hook}. For example, the default
value of that hook is as follows:

@lisp
(add-hook 'mastodon-toot-mode-hook
          (lambda ()
              (auto-fill-mode -1)))
@end lisp

@enumerate
@item
@anchor{Keybindings (1)}Keybindings


@multitable {aaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
@headitem Key
@tab Action
@item @samp{C-c C-c}
@tab Send toot
@item @samp{C-c C-k}
@tab Cancel toot
@item @samp{C-c C-w}
@tab Add content warning
@item @samp{C-c C-v}
@tab Change toot visibility
@item @samp{C-c C-n}
@tab Add sensitive media/nsfw flag
@item @samp{C-c C-a}
@tab Upload attachment(s)
@item @samp{C-c !}
@tab Remove all attachments
@item @samp{C-c C-e}
@tab Insert emoji
@item @samp{C-c C-p}
@tab Create a poll
@item @samp{C-c C-l}
@tab Set toot language
@item @samp{-C-c C-s}
@tab Schedule toot
@end multitable

@item
@anchor{Autocompletion of mentions tags and emoji}Autocompletion of mentions, tags and emoji


Autocompletion of mentions, tags, and emojis is provided by
@samp{completion-at-point-functions} (capf) backends.
@samp{mastodon-toot--enable-completion} is enabled by default.

To trigger completion, type a prefix followed by a few letters, @samp{@@} for
mentions, @samp{#} for tags, and @samp{:} for emoji (for now this only works when using @samp{emojify.el}).

If you want to enable @samp{company-mode} in the toot compose buffer, set
@samp{mastodon-toot--use-company-for-completion} to @samp{t}. (@samp{mastodon.el} used to run its
own native company backends, but these have been removed in favour of capfs.)

If you don’t run @samp{company} and want immediate, keyless completion, you’ll need
to have another completion engine running that handles capfs. A common
combination is @samp{consult} and @samp{corfu}.

@item
@anchor{Draft toots}Draft toots


@itemize
@item
Compose buffer text is saved as you type, kept in @samp{mastodon-toot-current-toot-text}.
@item
@samp{mastodon-toot--save-draft}: save the current toot as a draft.
@item
@samp{mastodon-toot--open-draft-toot}: Open a compose buffer and insert one of your draft toots.
@item
@samp{mastodon-toot--delete-draft-toot}: Delete a draft toot.
@item
@samp{mastodon-toot--delete-all-drafts}: Delete all your drafts.
@end itemize
@end enumerate

@node Other commands and account settings
@subsection Other commands and account settings:

In addition to @samp{mastodon}, the following three functions are autoloaded and should
work without first loading a @samp{mastodon.el} buffer:
@itemize
@item
@samp{mastodon-toot}: Compose new toot
@item
@samp{mastodon-notifications-get}: View all notifications
@item
@samp{mastodon-url-lookup}: Attempt to load a URL in @samp{mastodon.el}. URL may be at
point or provided in the minibuffer.
@end itemize


@itemize
@item
@samp{mastodon-tl--view-instance-description}: View information about the instance
that the author of the toot at point is on.
@item
@samp{mastodon-tl--view-own-instance}: View information about your own instance.
@item
@samp{mastodon-search--trending-tags}: View a list of trending hashtags on your
instance.
@item
@samp{mastodon-search--trending-statuses}: View a list of trending statuses on your instance.
@end itemize


@itemize
@item
@samp{mastodon-tl--add-toot-account-at-point-to-list}: Add the account of the toot at point to a list.
@end itemize


@itemize
@item
@samp{mastodon-tl--dm-user}: Send a direct message to one of the users at point.
@end itemize


@itemize
@item
@samp{mastodon-profile--add-private-note-to-account}: Add a private note to another user’s account.
@item
@samp{mastodon-profile--view-account-private-note}: View a private note on a user’s account.
@end itemize


@itemize
@item
@samp{mastodon-profile--show-familiar-followers}: Show a list of “familiar followers” for a given account. Familiar followers are accounts that you follow, and that follow the account.
@end itemize


@itemize
@item
@samp{mastodon-tl--follow-tag}: Follow a tag (works like following a user)
@item
@samp{mastodon-tl--unfollow-tag}: Unfollow a tag
@item
@samp{mastodon-tl--list-followed-tags}: View a list of tags you're following.
@item
@samp{mastodon-tl--followed-tags-timeline}: View a timeline of all your followed tags.
@item
@samp{mastodon-tl--some-followed-tags-timleine}: View a timeline of multiple tags, from your followed tags or any other.
@end itemize


@itemize
@item
@samp{mastodon-switch-to-buffer}: switch between mastodon buffers.
@end itemize


@itemize
@item
@samp{mastodon-profile--update-display-name}: Update the display name for your
account.
@item
@samp{mastodon-profile--update-user-profile-note}: Update your bio note.
@item
@samp{mastodon-profile--update-meta-fields}: Update your metadata fields.
@item
@samp{mastodon-profile--set-default-toot-visibility}: Set the default visibility
for your toots.
@item
@samp{mastodon-profile--account-locked-toggle}: Toggle the locked status of your
account. Locked accounts have to manually approve follow requests.
@item
@samp{mastodon-profile--account-discoverable-toggle}: Toggle the discoverable
status of your account. Non-discoverable accounts are not listed in the
profile directory.
@item
@samp{mastodon-profile--account-bot-toggle}: Toggle whether your account is flagged
as a bot.
@item
@samp{mastodon-profile--account-sensitive-toggle}: Toggle whether your posts are
marked as sensitive (nsfw) by default.
@end itemize

@node Customization
@subsection Customization

See @samp{M-x customize-group RET mastodon} to view all customize options.

@itemize
@item
Timeline options:
@itemize
@item
Use proportional fonts
@item
Default number of posts displayed
@item
Timestamp format
@item
Relative timestamps
@item
Display user avatars
@item
Avatar image height
@item
Enable image caching
@item
Hide replies in timelines
@item
Show toot stats in byline
@end itemize

@item
Compose options:
@itemize
@item
Completion style for mentions and tags
@item
Enable custom emoji
@item
Display toot being replied to
@item
Set default reply visibility
@end itemize

@item
Nofitication options:
@itemize
@item
Display user's profile note in follow requests
@end itemize
@end itemize

@node Commands and variables index
@subsection Commands and variables index

An index of all user-facing commands and custom variables is available here: @uref{mastodon-index.org, mastodon-index.org}.

You can also hit @samp{?} in any @samp{mastodon.el} buffer to see the available bindings, or run @samp{M-X} (upper-case @samp{X}) to view all commands in the buffer with completion, and call one.

@node Alternative timeline layout
@subsection Alternative timeline layout

The incomparable Nicholas Rougier has written an alternative timeline layout
for @samp{mastodon.el}.

The repo is at @uref{https://github.com/rougier/mastodon-alt, mastodon-alt}.

@node Live-updating timelines @samp{mastodon-async-mode}
@subsection Live-updating timelines: @samp{mastodon-async-mode}

(code taken from @uref{https://github.com/alexjgriffith/mastodon-future.el, mastodon-future}.)

Works for federated, local, and home timelines and for notifications. It's a
little touchy, one thing to avoid is trying to load a timeline more than once
at a time. It can go off the rails a bit, but it's still pretty cool. The
current maintainer of @samp{mastodon.el} is unable to debug or improve this feature.

To enable, it, add @samp{(require 'mastodon-async)} to your @samp{init.el}. Then you can
view a timeline with one of the commands that begin with
@samp{mastodon-async--stream-}.

@node Translating toots
@subsection Translating toots

You can translate toots with @samp{mastodon-toot--translate-toot-text} (@samp{a} in a
timeline). At the moment this requires @uref{https://codeberg.org/martianh/lingva.el, lingva.el}, a little interface I wrote
to @uref{https://lingva.ml, lingva.ml}, to be installed to work.

You could easily modify the simple function to use your Emacs translator of
choice (@samp{libretrans.el} , @samp{google-translate}, @samp{babel}, @samp{go-translate}, etc.), you just
need to fetch the toot's content with @samp{(mastodon-tl--content toot)} and pass it
to your translator function as its text argument. Here's what
@samp{mastodon-toot--translate-toot-text} looks like:

@lisp
(defun mastodon-toot--translate-toot-text ()
  "Translate text of toot at point.
  Uses `lingva.el'."
    (interactive)
    (let* ((toot (mastodon-tl--property 'item-json)))
      (if toot
          (lingva-translate nil (mastodon-tl--content toot))
        (message "No toot to translate?"))))
@end lisp

@node Bookmarks and @samp{mastodonel}
@subsection Bookmarks and @samp{mastodon.el}

@samp{mastodon.el} implements a basic bookmark record and handler. Currently, this means that you can bookmark a post item and later load it in thread view. This could be expanded to any item with an id, but probably not to things like timeline views. If you want to be able to bookmark something, open an issue and ask, it's trivial to expand the bookmarking code.

@node Dependencies
@section Dependencies

Hard dependencies (should all install with @samp{mastodon.el}):
@itemize
@item
@samp{request} (for uploading attachments), @uref{https://github.com/tkf/emacs-request, emacs-request}
@item
@samp{persist} for storing some settings across sessions
@end itemize

Optional dependencies (install yourself, @samp{mastodon.el} can use them):
@itemize
@item
@samp{emojify} to use custom emoji (else we use builtin @samp{emoji.el})
@item
@samp{mpv} and @samp{mpv.el} for viewing videos and gifs
@item
@samp{lingva.el} for translating toots
@end itemize

@node Network compatibility
@section Network compatibility

@samp{mastodon.el} should work with ActivityPub servers that implement the Mastodon API@.

Apart from Mastodon itself, it is currently known to work with:
@itemize
@item
Pleroma (@uref{https://pleroma.social/, pleroma.social})
@item
Akkoma (@uref{https://akkoma.social/, akkoma.social})
@item
Gotosocial (@uref{https://gotosocial.org/, gotosocial.org})
@end itemize

It does not support the non-Mastodon API servers Misskey (@uref{https://misskey.io/, misskey.io}), Firefish (@uref{https://joinfirefish.org/, joinfirefish.org}, formerly Calkey) and Friendica, but it should fully support displaying and interacting with posts and users on those platforms.

If you attempt to use @samp{mastodon.el} with a server and run into problems, feel
free to open an issue.

@node Contributing
@section Contributing

PRs, issues, feature requests, and general feedback are very welcome!

If you prefer emailing patches to the process described below, feel free to send them on. Ideally they'd be patches that can be applied with @samp{git am}, if you want to actually contribute a commit.

@menu
* Bug reports::
* Fixes and features::
* Coding style::
@end menu

@node Bug reports
@subsection Bug reports

@enumerate
@item
@samp{mastodon.el} has bugs, as well as lots of room for improvement.
@item
I receive very little feedback, so if I don't run into the bug it often doesn't get fixed.
@item
If you run into something that seems broken, first try running @samp{mastodon.el}
in emacs with no init file (i.e. @samp{emacs -q} (instructions and code for doing
this are @uref{https://codeberg.org/martianh/mastodon.el/issues/300, here}) to see if it also happens independently of your own config
(it probably does).
@item
Else enable debug on error (@samp{toggle-debug-on-error}), make the bug happen again,
and copy the backtrace that appears.
@item
Open an issue here and explain what is going on. Provide your emacs version and what kind of server your account is on.
@end enumerate

@node Fixes and features
@subsection Fixes and features

@enumerate
@item
Create an @uref{https://codeberg.org/martianh/mastodon.el/issues, issue} detailing what you'd like to do.
@item
Fork the repository and create a branch off of @samp{develop}.
@item
Run the tests and ensure that your code doesn't break any of them.
@item
Create a pull request (to develop) referencing the issue created in step 1.
@end enumerate

@node Coding style
@subsection Coding style

@itemize
@item
This library uses an unconvential double dash (@samp{--}) between file namespaces and function names, which contradicts normal Elisp style. This needs to be respected until the whole library is changed.
@item
Use @samp{aggressive-indent-mode} or similar to keep your code indented.
@item
Single spaces end sentences in docstrings.
@item
There's no need for a blank line after the first docstring line (one is added automatically when documentation is displayed).
@end itemize

@node Supporting @samp{mastodonel}
@section Supporting @samp{mastodon.el}

If you'd like to support continued development of @samp{mastodon.el}, I accept
donations via paypal: @uref{https://paypal.me/martianh, paypal.me/martianh}. If you would prefer a different
payment method, please write to me at <martianhiatus [at] riseup [dot] net> and I can
provide IBAN or other bank account details.

I don't have a tech worker's income, so even a small tip would help out.

@node Contributors
@section Contributors

@samp{mastodon.el} is the work of a number of people.

Some significant contributors are:

@itemize
@item
@uref{https://github.com/jdenen} [original author]
@item
@uref{http://atomized.org}
@item
@uref{https://alexjgriffith.itch.io}
@item
@uref{https://github.com/hdurer}
@item
@uref{https://codeberg.org/Red_Starfish}
@end itemize

@node screenshots
@section screenshots

Here's a (federated) timeline:

@image{screenshot-tl,,,,png}

Here's a notifcations view plus a compose buffer:

@image{screenshot-notifs+compose,,,,png}

@bye