diff options
| -rw-r--r-- | README.org | 336 |
1 files changed, 157 insertions, 179 deletions
@@ -1,115 +1,8 @@ #+OPTIONS: toc:nil -* mastodon.el updated - -This is an updated version of the great but seemingly dormant mastodon client for emacs. - -This is now the version available via MELPA. - -[The original readme is below.] - -It adds the following features: - -| Profiles: | | -| | display profile metadata fields | -| | display pinned toots first | -| | display relationship (follows you/followed by you) | -| | display toots/follows/followers counts | -| | links/tags/mentions in profile bios are active links | -| | show a lock icon for locked accounts | -| =G= | view follow suggestions | -| =R=, =a=, =r= | view/accept/reject follow requests | -| =V= | view your favorited toots | -| =i= | toggle pinning of toots | -| =U= | update your profile bio note | -| =O= | jump to own profile | -| Notifications: | | -| | follow requests now also appear in notifications | -| =a=, =j= | accept/reject follow request | -| | notifications for when a user posts (=mastodon-tl--enable-notify-user-posts=) | -| Timelines: | | -| =C= | copy url of toot at point | -| =d= | delete your toot at point, and reload current timeline | -| =D= | delete and redraft toot at point, preserving reply/CW/visibility | -| =W=, =M=, =B= | (un)follow, (un)mute, (un)block author of toot at point | -| =k=, =K= | toggle bookmark of toot at point, view bookmarked toots | -| =I=, =c=, =d= | view, create, and delete filters | -| | display image captions | -| | display polls and vote on them | -| | images are links to the full image, can be zoomed/rotated/saved (see image keymap) | -| | images scale properly | -| | toot visibility (direct, followers only) icon appears in toot bylines | -| | display toot's number of favorites, boosts and replies | -| | play gifs and videos (requires =mpv= to be installed) | -| | customize option to cache images | -| Toots: | | -| | mention booster in replies by default | -| | replies preserve visibility status/CW of original toot | -| | autocompletion of user mentions, via =company-mode= (must be installed to work) | -| =C-c C-a= | media uploads, asynchronous | -| | media upload previews displayed in toot compose buffer | -| =C-c C-n= | and sensitive media/nsfw flag | -| =C-c C-e= | add emoji (if =emojify= installed) | -| | download and use your instance's custom emoji | -| | server's maximum toot length shown in toot compose buffer | -| Search: | | -| =S= | search (posts, users, tags) (NB: only posts you have interacted with are searched) | -| | | - -It also makes some small cosmetic changes to make timelines easier to read, and makes some functions asynchronous, based on https://github.com/ieure/mastodon.el. +* README -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. - -** 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. - -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-=. - -** translating toots - -You can translate toots with =mastodon-toot--translate-toot-text=. At the moment this requires [[https://codeberg.org/martianh/lingva.el][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 (=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: - -#+begin_src emacs-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_src - -** NB: dependencies - -This version depends on the library =request= (for uploading attachments). You can install it from MELPA, or https://github.com/tkf/emacs-request. It also depends on =seq=. - -Optional dependencies: -- =company= for autocompletion of mentions when composing a toot -- =emojify= for inserting and viewing emojis -- =mpv= and =mpv.el= for viewing videos and gifs -- =lingva.el= for translating toots - -** NB: bugs - -This repo also incorporates fixes for two bugs that were never merged into the upstream repo: -- https://github.com/jdenen/mastodon.el/issues/227 (and https://github.com/jdenen/mastodon.el/issues/234) -- https://github.com/jdenen/mastodon.el/issues/228 - -** contributing - -Contributions are welcome. - -1. Create an here on codeberg detailing the feature you'd like to add. -2. Fork the repository and create a branch off of =develop=. -3. Create a pull request referencing the issue created in step 1. - -* Original README +=mastodon.el= is an Emacs client for the Mastodon and Pleroma social networks. For info see https://joinmastodon.org/. ** Installation @@ -128,6 +21,8 @@ Or, with =use-package=: :ensure t) #+END_SRC +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. + *** MELPA Add =MELPA= to your archives: @@ -171,12 +66,13 @@ Or, with =use-package=: #+END_SRC ** Usage -*** Instance + +*** 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 +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 @@ -192,95 +88,181 @@ 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 have been using mastodon.el before this change and the above -steps do not work it's advisable that you delete the old file specified -by =mastodon-client--token-file= and restart Emacs and follow the steps -again. +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. *** Timelines =M-x mastodon= -Opens a =*mastodon-home*= buffer in the major mode so you can see toots. 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=. +Opens a =*mastodon-home*= buffer in the major mode and displays toots. 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=. **** Keybindings -|-----------------+---------------------------------------------------------| -| Key | Action | -|-----------------+---------------------------------------------------------| -| | /Help/ | -| =?= | Open context menu 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 | -| =u= | Update timeline | -| =#= | Prompt for tag and open its timeline | -| =A= | Open author profile of toot under =point= | -| =F= | Open federated timeline | -| =H= | Open home timeline | -| =L= | Open local timeline | -| =N= | Open notifications timeline | -| =P= | Open profile of user attached to toot under =point= | -| =T= | Open thread buffer for toot under =point= | -| | /Toot actions/ | -| =c= | Toggle content warning content | -| =b= | Boost toot under =point= | -| =f= | Favourite toot under =point= | -| =r= | Reply to toot under =point= | -| =n= | Compose a new toot | -| | /Switching to other buffers/ | -| | /Quitting/ | -| =q= | Quit mastodon buffer, leave window open | -| =Q= | Quit mastodon buffer and kill window | -|-----------------+---------------------------------------------------------| +|---------------+-----------------------------------------------------------------------| +| Key | Action | +|---------------+-----------------------------------------------------------------------| +| | /Help/ | +| =?= | Open context menu 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 | +| =u= | Update timeline | +| =#= | Prompt for tag and open its timeline | +| =A= | Open author profile of toot under =point= | +| =F= | Open federated timeline | +| =H= | Open home timeline | +| =L= | Open local timeline | +| =N= | Open notifications timeline | +| =P= | Open profile of user attached to toot under =point= | +| =O= | View own profile | +| =U= | update your profile bio note | +| =T= | Open thread buffer for toot under =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=, =r= | view/accept/reject follow requests | +| =G= | view follow suggestions | +| =V= | view your favorited toots | +| =K= | view bookmarked toots | +|---------------+-----------------------------------------------------------------------| +| | /Toot actions/ | +| =c= | Toggle content warning content | +| =b= | Boost toot under =point= | +| =f= | Favourite toot under =point= | +| =r= | Reply to toot under =point= | +| =t= | Compose a new toot | +| =v= | Vote on poll at point | +| =C= | copy url of toot at point | +| =C-RET= | play video/gif at point (requires =mpv=) | +| =i= | (un)pin toot at point | +| =d= | delete your toot at point, and reload current timeline | +| =D= | delete and redraft toot at point, preserving reply/CW/visibility | +| =W=, =M=, =B= | (un)follow, (un)mute, (un)block author of toot at point | +| =k= | toggle bookmark of toot at point | +|---------------+-----------------------------------------------------------------------| +| | Notifications view | +| =a=, =j= | accept/reject follow request | +|---------------+-----------------------------------------------------------------------| +| | /Switching to other buffers/ | +| | /Quitting/ | +| =q= | Quit mastodon buffer, leave window open | +| =Q= | Quit mastodon buffer and kill window | +|---------------+-----------------------------------------------------------------------| **** Legend -|--------+-------------------------| -| Marker | Meaning | -|--------+-------------------------| -| =(B)= | I boosted this toot. | -| =(F)= | I favourited this toot. | -|--------+-------------------------| +|----------------+------------------------| +| Marker | Meaning | +|----------------+------------------------| +| =(B)= | I boosted this toot | +| =(F)= | I favourited this toot | +| (=K=) (or emoji) | I bookmarked this toot | +|----------------+------------------------| -*** Toot toot +*** Composing toots -=M-x mastodon-toot= +=M-x mastodon-toot= (or =t= from a mastodon.el buffer). -Pops a new buffer/window with a =mastodon-toot= minor mode. Enter the +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. -If you have not previously authenticated, you will be prompted for your -account email and password. *NOTE*: Email and password are NOT stored by mastodon.el. +Autocompletion of mentions is provided by a mastodon company backend (requires =company-mode=). -Authentication stores your access token in the =mastodon-auth--token= -variable. It is not stored on your filesystem, so you will have to -re-authenticate when you close/reopen Emacs. +Replies preserve visibility status/content warnings, and include boosters by default. -**** Customization -The default toot visibility can be changed by setting or customizing the =mastodon-toot--default-visibility= variable. Valid values are ="public"=, ="unlisted"=, ="private"=, or =direct=. +Server's max toot length, and attachment previews, are shown. -Toot visibility can also be changed on a per-toot basis from the new toot buffer. +You can download and use your instance's custom emoji +(=mastodon-toot--download-custom-emoji=, =mastodon-toot--enable-custom-emoji=). **** 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 | -|-----------+------------------------| +|---------+----------------------------------| +| 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) | +|---------+----------------------------------| + +*** Customization + +See =M-x customize-group RET mastodon= to view all customize options. + +- Timeline options: + - Use proportional fonts + - Timestamp format + - Relative timestamps + - Display use avatars + - Avatar image hight + - Enable image caching + +- Compose options: + - Default toot visibility, using =mastodon-toot--default-visibility= variable. Valid values are ="public"=, ="unlisted"=, ="private"=, or =direct=. + - Completions for mentions + - Enable custom emoji + +*** 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 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-=. + +*** translating toots + +You can translate toots with =mastodon-toot--translate-toot-text=. At the moment +this requires [[https://codeberg.org/martianh/lingva.el][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: + +#+begin_src emacs-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_src -** Roadmap +** dependencies -[[https://github.com/jdenen/mastodon.el/milestone/1][Here]] are the features I plan to implement before putting mastodon.el on MELPA. +This version depends on the library =request= (for uploading attachments). You +can install it from MELPA, or https://github.com/tkf/emacs-request. -[[https://github.com/jdenen/mastodon.el/milestone/2][Here]] are the plans I have for the =1.0.0= release. +Optional dependencies: +- =company= for autocompletion of mentions when composing a toot +- =emojify= for inserting and viewing emojis +- =mpv= and =mpv.el= for viewing videos and gifs +- =lingva.el= for translating toots ** Contributing @@ -297,7 +279,3 @@ PRs, issues, and feature requests are very welcome! 1. In an [[https://github.com/jdenen/mastodon.el/issues][issue]], let me know that you're working to fix it. 2. Fork the repository and create a branch off of =develop=. 3. Create a pull request referencing the issue from step 1. - -** Connect - -If you want to get in touch with me, give me a [[https://mastodon.social/@johnson][toot]] or leave an [[https://github.com/jdenen/mastodon.el/issues][issue]]. |