path: root/README.info

This is README.info, produced by makeinfo version 6.7 from README.texi.


File: README.info,  Node: Top,  Next: README,  Up: (dir)

* Menu:

* README::

— The Detailed Node Listing —

README

* Installation::
* Usage::
* Dependencies::
* Network compatibility::
* Contributing::
* Supporting ‘mastodon.el’: Supporting mastodonel.
* Contributors::

Installation

* MELPA::
* Emoji::
* Discover::

Usage

* Logging in to your instance::
* Timelines::
* Composing toots::
* Other commands and account settings::
* Customization::
* Alternative timeline layout::
* Live-updating timelines mastodon-async-mode::
* Translating toots::

Timelines

* Keybindings::
* Toot byline legend::

Composing toots

* Keybindings: Keybindings (1).
* Draft toots::

Contributing

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



File: README.info,  Node: README,  Prev: Top,  Up: Top

README
******

‘mastodon.el’ is an Emacs client for the AcitivityPub social networks
that implement the Mastodon API.  For info see
<https://joinmastodon.org/>.

* Menu:

* Installation::
* Usage::
* Dependencies::
* Network compatibility::
* Contributing::
* Supporting ‘mastodon.el’: Supporting mastodonel.
* Contributors::


File: README.info,  Node: Installation,  Next: Usage,  Up: README

Installation
============

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

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

   Or, with ‘use-package’:

     (use-package mastodon
       :ensure t)

   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.

* Menu:

* MELPA::
* Emoji::
* Discover::


File: README.info,  Node: MELPA,  Next: Emoji,  Up: Installation

MELPA
-----

Add ‘MELPA’ to your archives:

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

   Update and install:

   ‘M-x package-refresh-contents RET’

   ‘M-x package-install RET mastodon RET’


File: README.info,  Node: Emoji,  Next: Discover,  Prev: MELPA,  Up: Installation

Emoji
-----

‘mastodon-mode’ will enable Emojify
(https://github.com/iqbalansari/emacs-emojify) if it is loaded in your
Emacs environment, so there’s no need to write your own hook anymore.
‘emojify-mode’ is not required.


File: README.info,  Node: Discover,  Prev: Emoji,  Up: Installation

Discover
--------

‘mastodon-mode’ can provide a context menu for its keybindings if
Discover (https://github.com/mickeynp/discover.el) is installed.  It is
not required.

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

     (require 'mastodon-discover)
     (with-eval-after-load 'mastodon (mastodon-discover))

   Or, with ‘use-package’:

     (use-package mastodon
       :ensure t
       :config
       (mastodon-discover))


File: README.info,  Node: Usage,  Next: Dependencies,  Prev: Installation,  Up: README

Usage
=====

* Menu:

* Logging in to your instance::
* Timelines::
* Composing toots::
* Other commands and account settings::
* Customization::
* Alternative timeline layout::
* Live-updating timelines mastodon-async-mode::
* Translating toots::


File: README.info,  Node: Logging in to your instance,  Next: Timelines,  Up: Usage

Logging in to your instance
---------------------------

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

  1. ‘mastodon-instance-url’
  2. ‘mastodon-active-user’

   (see their doc strings for details).  For example If you want to post
toots as “example_user@social.instance.org”, then put this in your init
file:

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

   Then *restart* Emacs and run ‘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
‘mastodon-client--token-file’ and restart Emacs and follow the steps
again.


File: README.info,  Node: Timelines,  Next: Composing toots,  Prev: Logging in to your instance,  Up: Usage

Timelines
---------

‘M-x mastodon’

   Opens a ‘*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 ‘mastodon-token-file’ does not contain ‘:client_id’ and
‘:client_secret’.

* Menu:

* Keybindings::
* Toot byline legend::


File: README.info,  Node: Keybindings,  Next: Toot byline legend,  Up: Timelines

Keybindings
...........

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


File: README.info,  Node: Toot byline legend,  Prev: Keybindings,  Up: Timelines

Toot byline legend
..................

Marker             Meaning
--------------------------------------------
‘(B)’              I boosted this toot
‘(F)’              I favourited this toot
‘(🔖)’ (or          I bookmarked this toot
(‘K’))


File: README.info,  Node: Composing toots,  Next: Other commands and account settings,  Prev: Timelines,  Up: Usage

Composing toots
---------------

‘M-x mastodon-toot’ (or ‘t’ from a mastodon.el buffer).

   Pops a new buffer/window in ‘mastodon-toot’ minor mode.  Enter the
contents of your toot here.  ‘C-c C-c’ sends the toot.  ‘C-c C-k’
cancels.  Both actions kill the buffer and window.

   Autocompletion of mentions and tags is provided by
‘completion-at-point-functions’ (capf) backends.
‘mastodon-toot--enable-completion’ is enabled by default.  If you want
to enable ‘company-mode’ in the toot compose buffer, set
‘mastodon-toot--use-company-for-completion’ to ‘t’.  (‘mastodon.el’ used
to run its own native company backends, but these have been removed in
favour of capfs.)

   Replies preserve visibility status/content warnings, and include
boosters by default.

   Server’s max toot length, and attachment previews, are shown.

   You can download and use your instance’s custom emoji
(‘mastodon-toot--download-custom-emoji’,
‘mastodon-toot--enable-custom-emoji’).

* Menu:

* Keybindings: Keybindings (1).
* Draft toots::


File: README.info,  Node: Keybindings (1),  Next: Draft toots,  Up: Composing toots

Keybindings
...........

Key         Action
-------------------------------------------------
‘C-c C-c’   Send toot
‘C-c C-k’   Cancel toot
‘C-c C-w’   Add content warning
‘C-c C-v’   Change toot visibility
‘C-c C-n’   Add sensitive media/nsfw flag
‘C-c C-a’   Upload attachment(s)
‘C-c !’     Remove all attachments
‘C-c C-e’   Add emoji (if ‘emojify’ installed)
‘C-c C-p’   Create a poll
‘C-c C-l’   Set toot language


File: README.info,  Node: Draft toots,  Prev: Keybindings (1),  Up: Composing toots

Draft toots
...........

   • Compose buffer text is saved as you type, kept in
     ‘mastodon-toot-current-toot-text’.
   • ‘mastodon-toot--save-draft’: save the current toot as a draft.
   • ‘mastodon-toot--open-draft-toot’: Open a compose buffer and insert
     one of your draft toots.
   • ‘mastodon-toot--delete-draft-toot’: Delete a draft toot.
   • ‘mastodon-toot--delete-all-drafts’: Delete all your drafts.


File: README.info,  Node: Other commands and account settings,  Next: Customization,  Prev: Composing toots,  Up: Usage

Other commands and account settings:
------------------------------------

In addition to ‘mastodon’, the following three functions are autoloaded
and should work without first loading ‘mastodon.el’:
   • ‘mastodon-toot’: Compose new toot
   • ‘mastodon-notifications-get’: View all notifications
   • ‘mastodon-url-lookup’: Attempt to load a URL in ‘mastodon.el’.  URL
     may be at point or provided in the minibuffer.

   • ‘mastodon-tl--view-instance-description’: View information about
     the instance that the author of the toot at point is on.
   • ‘mastodon-tl--view-own-instance’: View information about your own
     instance.
   • ‘mastodon-search--trending-tags’: View a list of trending hashtags
     on your instance.

   • ‘mastodon-tl--add-toot-account-at-point-to-list’: Add the account
     of the toot at point to a list.

   • ‘mastodon-tl--follow-tag’: Follow a tag (works like following a
     user)
   • ‘mastodon-tl--unfollow-tag’: Unfollow a tag
   • ‘mastodon-tl--list-followed-tags’: View a list of tags you’re
     following.

   • ‘mastodon-switch-to-buffer’: switch between mastodon buffers.

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


File: README.info,  Node: Customization,  Next: Alternative timeline layout,  Prev: Other commands and account settings,  Up: Usage

Customization
-------------

See ‘M-x customize-group RET mastodon’ to view all customize options.

   • Timeline options:
        • Use proportional fonts
        • Default number of posts displayed
        • Timestamp format
        • Relative timestamps
        • Display user avatars
        • Avatar image height
        • Enable image caching
        • Hide replies in timelines

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


File: README.info,  Node: Alternative timeline layout,  Next: Live-updating timelines mastodon-async-mode,  Prev: Customization,  Up: Usage

Alternative timeline layout
---------------------------

The incomparable Nicholas Rougier has written an alternative timeline
layout for ‘mastodon.el’.

   The repo is at <https://github.com/rougier/mastodon-alt>.


File: README.info,  Node: Live-updating timelines mastodon-async-mode,  Next: Translating toots,  Prev: Alternative timeline layout,  Up: Usage

Live-updating timelines: ‘mastodon-async-mode’
----------------------------------------------

(code taken from <https://github.com/alexjgriffith/mastodon-future.el>.)

   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 ‘mastodon.el’ is unable to debug
or improve this feature.

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


File: README.info,  Node: Translating toots,  Prev: Live-updating timelines mastodon-async-mode,  Up: Usage

Translating toots
-----------------

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

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

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


File: README.info,  Node: Dependencies,  Next: Network compatibility,  Prev: Usage,  Up: README

Dependencies
============

Hard dependencies (should all install with ‘mastodon.el’):
   • ‘request’ (for uploading attachments),
     <https://github.com/tkf/emacs-request>
   • ‘persist’ for storing some settings across sessions
   • ‘ts’ for poll relative expiry times

   Optional dependencies:
   • ‘emojify’ for inserting and viewing emojis
   • ‘mpv’ and ‘mpv.el’ for viewing videos and gifs
   • ‘lingva.el’ for translating toots


File: README.info,  Node: Network compatibility,  Next: Contributing,  Prev: Dependencies,  Up: README

Network compatibility
=====================

‘mastodon.el’ should work with ActivityPub servers that implement the
Mastodon API.

   Apart from Mastodon itself, it is currently known to work with
Pleroma and Gotosocial.  If you attempt to use ‘mastodon.el’ with
another server that implements the Mastodon API and run into problems,
feel free to open an issue.


File: README.info,  Node: Contributing,  Next: Supporting mastodonel,  Prev: Network compatibility,  Up: README

Contributing
============

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

* Menu:

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


File: README.info,  Node: Bug reports,  Next: Fixes and features,  Up: Contributing

Bug reports
-----------

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


File: README.info,  Node: Fixes and features,  Next: Coding style,  Prev: Bug reports,  Up: Contributing

Fixes and features
------------------

  1. Create an issue (https://codeberg.org/martianh/mastodon.el/issues)
     detailing what you’d like to do.
  2. Fork the repository and create a branch off of ‘develop’.
  3. Run the tests and ensure that your code doesn’t break any of them.
  4. Create a pull request referencing the issue created in step 1.


File: README.info,  Node: Coding style,  Prev: Fixes and features,  Up: Contributing

Coding style
------------

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


File: README.info,  Node: Supporting mastodonel,  Next: Contributors,  Prev: Contributing,  Up: README

Supporting ‘mastodon.el’
========================

If you’d like to support continued development of ‘mastodon.el’, I
accept donations via paypal: paypal.me/martianh
(https://paypal.me/martianh).  If you would prefer a different payment
method, write to me at that address and I can provide IBAN or other
details.

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


File: README.info,  Node: Contributors,  Prev: Supporting mastodonel,  Up: README

Contributors
============

‘mastodon.el’ is the work of a number of people.

   Some significant contributors are:

   • <https://github.com/jdenen> [original author]
   • <http://atomized.org>
   • <https://alexjgriffith.itch.io>
   • <https://github.com/hdurer>
   • <https://codeberg.org/Red_Starfish>



Tag Table:
Node: Top73
Node: README828
Node: Installation1221
Node: MELPA1747
Node: Emoji2101
Node: Discover2419
Node: Usage2957
Node: Logging in to your instance3296
Node: Timelines4283
Node: Keybindings4788
Node: Toot byline legend8697
Node: Composing toots9042
Node: Keybindings (1)10241
Node: Draft toots10793
Node: Other commands and account settings11328
Node: Customization13617
Node: Alternative timeline layout14351
Node: Live-updating timelines mastodon-async-mode14714
Node: Translating toots15536
Node: Dependencies16661
Node: Network compatibility17243
Node: Contributing17719
Node: Bug reports17998
Node: Fixes and features18890
Node: Coding style19359
Node: Supporting mastodonel19969
Node: Contributors20481

End Tag Table


Local Variables:
coding: utf-8
End: