aboutsummaryrefslogtreecommitdiff
path: root/mastodon.texi
blob: 761ac8f2d2781c6ed4b1c1abf64a139750289fff (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
\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 fediverse services using the Mastodon API.
@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::
* mastodon hydra::
* 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 28.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. From personal experience, @samp{emojify} also tends to result in less TOFU@.

@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::
* mastodon hydra::
* 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{!}
@tab toggle folding of toot at point
@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-tl--get-remote-local-timeline}: View a local timeline of a remote instance.
@item
@samp{mastodon-tl--remote-tag-timeline}: View a tag timeline on a remote instance.
@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 mastodon hydra
@subsection mastodon hydra

A user made a hydra for handling basic mastodon.el commands. It's available at
@uref{https://holgerschurig.github.io/en/emacs-mastodon-hydra/}.

@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, as 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 <mousebot@@disroot.org> 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}

Here's a user settings transient (active values green, current server values commented and, if a boolean, underlined):

@image{screenshot-transient-1,,,,jpg}

Here's a user profile fields transient (changed fields green, current server values commented):

@image{screenshot-transient-2,,,,jpg}

@bye