diff options
| -rw-r--r-- | dir | 18 | ||||
| -rw-r--r-- | mastodon.info | 645 | ||||
| -rw-r--r-- | mastodon.texi | 732 |
3 files changed, 1395 insertions, 0 deletions
@@ -0,0 +1,18 @@ +This is the file .../info/dir, which contains the +topmost node of the Info hierarchy, called (dir)Top. +The first time you invoke Info you start off looking at this node. + +File: dir, Node: Top This is the top of the INFO tree + + This (the Directory node) gives a menu of major topics. + Typing "q" exits, "H" lists all Info commands, "d" returns here, + "h" gives a primer for first-timers, + "mEmacs<Return>" visits the Emacs manual, etc. + + In Emacs, you can click mouse button 2 on a menu item or cross reference + to select it. + +* Menu: + +Emacs +* Mastodon: (mastodon). Client for Mastodon on ActivityPub networks. diff --git a/mastodon.info b/mastodon.info new file mode 100644 index 0000000..f7302de --- /dev/null +++ b/mastodon.info @@ -0,0 +1,645 @@ +This is mastodon.info, produced by makeinfo version 6.7 from +mastodon.texi. + +INFO-DIR-SECTION Emacs +START-INFO-DIR-ENTRY +* Mastodon: (mastodon). Client for Mastodon on ActivityPub networks. +END-INFO-DIR-ENTRY + + +File: mastodon.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:: + +Contributing + +* Bug reports:: +* Fixes and features:: +* Coding style:: + + + +File: mastodon.info, Node: README, Prev: Top, Up: Top + +1 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: mastodon.info, Node: Installation, Next: Usage, Up: README + +1.1 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: mastodon.info, Node: MELPA, Next: Emoji, Up: Installation + +1.1.1 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: mastodon.info, Node: Emoji, Next: Discover, Prev: MELPA, Up: Installation + +1.1.2 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: mastodon.info, Node: Discover, Prev: Emoji, Up: Installation + +1.1.3 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: mastodon.info, Node: Usage, Next: Dependencies, Prev: Installation, Up: README + +1.2 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: mastodon.info, Node: Logging in to your instance, Next: Timelines, Up: Usage + +1.2.1 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: mastodon.info, Node: Timelines, Next: Composing toots, Prev: Logging in to your instance, Up: Usage + +1.2.2 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’. + + 1. 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 + + 2. Toot byline legend + + Marker Meaning + -------------------------------------------- + ‘(B)’ I boosted this toot + ‘(F)’ I favourited this toot + ‘(🔖)’ (or I bookmarked this toot + (‘K’)) + + +File: mastodon.info, Node: Composing toots, Next: Other commands and account settings, Prev: Timelines, Up: Usage + +1.2.3 Composing toots +--------------------- + +‘M-x mastodon-toot’ (or ‘t’ from a mastodon.el buffer). + + Pops a new buffer/window in ‘text-mode’ and ‘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’). + + The compose buffer uses ‘text-mode’ so any configuration you have for +that mode will be enabled. If any of your existing config conflicts +with ‘mastodon-toot’, you can disable it in the +‘mastodon-toot-mode-hook’. For example, the default value of that hook +is as follows: + + (add-hook 'mastodon-toot-mode-hook + (lambda () + (auto-fill-mode -1))) + + 1. 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 + + 2. 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: mastodon.info, Node: Other commands and account settings, Next: Customization, Prev: Composing toots, Up: Usage + +1.2.4 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--dm-user’: Send a direct message to one of the users + at point. + + • ‘mastodon-profile--add-private-note-to-account’: Add a private note + to another user’s account. + • ‘mastodon-profile--view-account-private-note’: View a private note + on a user’s account. + + • ‘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. + + • ‘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: mastodon.info, Node: Customization, Next: Alternative timeline layout, Prev: Other commands and account settings, Up: Usage + +1.2.5 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: mastodon.info, Node: Alternative timeline layout, Next: Live-updating timelines mastodon-async-mode, Prev: Customization, Up: Usage + +1.2.6 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: mastodon.info, Node: Live-updating timelines mastodon-async-mode, Next: Translating toots, Prev: Alternative timeline layout, Up: Usage + +1.2.7 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: mastodon.info, Node: Translating toots, Prev: Live-updating timelines mastodon-async-mode, Up: Usage + +1.2.8 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: mastodon.info, Node: Dependencies, Next: Network compatibility, Prev: Usage, Up: README + +1.3 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: mastodon.info, Node: Network compatibility, Next: Contributing, Prev: Dependencies, Up: README + +1.4 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: mastodon.info, Node: Contributing, Next: Supporting mastodonel, Prev: Network compatibility, Up: README + +1.5 Contributing +================ + +PRs, issues, feature requests, and general feedback are very welcome! + +* Menu: + +* Bug reports:: +* Fixes and features:: +* Coding style:: + + +File: mastodon.info, Node: Bug reports, Next: Fixes and features, Up: Contributing + +1.5.1 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: mastodon.info, Node: Fixes and features, Next: Coding style, Prev: Bug reports, Up: Contributing + +1.5.2 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: mastodon.info, Node: Coding style, Prev: Fixes and features, Up: Contributing + +1.5.3 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: mastodon.info, Node: Supporting mastodonel, Next: Contributors, Prev: Contributing, Up: README + +1.6 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: mastodon.info, Node: Contributors, Prev: Supporting mastodonel, Up: README + +1.7 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: Top210 +Node: README850 +Node: Installation1249 +Node: MELPA1785 +Node: Emoji2153 +Node: Discover2485 +Node: Usage3037 +Node: Logging in to your instance3386 +Node: Timelines4383 +Ref: Keybindings4858 +Ref: Toot byline legend8976 +Node: Composing toots9248 +Ref: Keybindings (1)10825 +Ref: Draft toots11343 +Node: Other commands and account settings11814 +Node: Customization14637 +Node: Alternative timeline layout15385 +Node: Live-updating timelines mastodon-async-mode15762 +Node: Translating toots16598 +Node: Dependencies17737 +Node: Network compatibility18329 +Node: Contributing18815 +Node: Bug reports19104 +Node: Fixes and features20010 +Node: Coding style20493 +Node: Supporting mastodonel21117 +Node: Contributors21639 + +End Tag Table + + +Local Variables: +coding: utf-8 +End: diff --git a/mastodon.texi b/mastodon.texi new file mode 100644 index 0000000..eb303b2 --- /dev/null +++ b/mastodon.texi @@ -0,0 +1,732 @@ +\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:: + +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 @samp{mastodon-async-mode}:: +* Translating toots:: + +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/}. + +@menu +* Installation:: +* Usage:: +* Dependencies:: +* Network compatibility:: +* Contributing:: +* Supporting @samp{mastodon.el}: Supporting @samp{mastodonel}. +* Contributors:: +@end menu + +@node Installation +@section Installation + +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. + +@menu +* MELPA:: +* Emoji:: +* Discover:: +@end menu + +@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 Emoji +@subsection Emoji + +@samp{mastodon-mode} will enable @uref{https://github.com/iqbalansari/emacs-emojify, Emojify} if it is loaded in your Emacs environment, so +there's no need to write your own hook anymore. @samp{emojify-mode} is not required. + +@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:: +* Alternative timeline layout:: +* Live-updating timelines @samp{mastodon-async-mode}:: +* Translating toots:: +@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 + + +@multitable {aaaaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} +@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) +@item @samp{p} +@tab Go to previous item (toot, notification) +@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 +@item @samp{H} +@tab Open home timeline +@item @samp{L} +@tab Open local timeline +@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 favouriters of toot at point +@item @samp{.} +@tab view boosters of toot at point +@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, followers, following, and statuses without boosts +@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{(B)} +@tab I boosted this toot +@item @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). + +Pops 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. + +Autocompletion of mentions and tags is provided by @samp{completion-at-point-functions} (capf) backends. @samp{mastodon-toot--enable-completion} is enabled by default. 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.) + +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 +(@samp{mastodon-toot--download-custom-emoji}, @samp{mastodon-toot--enable-custom-emoji}). + +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 {aaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} +@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 Add emoji (if @samp{emojify} installed) +@item @samp{C-c C-p} +@tab Create a poll +@item @samp{C-c C-l} +@tab Set toot language +@end multitable + +@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 @samp{mastodon.el}: +@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. +@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. +@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 +@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 +@end itemize + +@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}. + +@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}.) + +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}, 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 'toot-json))) + (if toot + (lingva-translate nil (mastodon-tl--content toot)) + (message "No toot to translate?")))) +@end lisp + +@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} +@item +@samp{persist} for storing some settings across sessions +@item +@samp{ts} for poll relative expiry times +@end itemize + +Optional dependencies: +@itemize +@item +@samp{emojify} for inserting and viewing emojis +@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 Pleroma and +Gotosocial. If you attempt to use @samp{mastodon.el} with another server that +implements the Mastodon API and run into problems, feel free to open an issue. + +@node Contributing +@section Contributing + +PRs, issues, feature requests, and general feedback are very welcome! + +@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 +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 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, 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. + +@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 + +@bye
\ No newline at end of file |