add info documentation files

3 files changed, 1395 insertions, 0 deletions

diff --git a/dir b/dir
new file mode 100644
index 0000000..0b33fbe
--- /dev/null
+++ b/dir
@@ -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