add README.info

1 files changed, 653 insertions, 0 deletions

diff --git a/README.info b/README.info
new file mode 100644
index 0000000..63969d0
--- /dev/null
+++ b/README.info
@@ -0,0 +1,653 @@
+This is README.info, produced by makeinfo version 6.7 from README.texi.
+
+
+File: README.info,  Node: Top,  Next: README,  Up: (dir)
+
+* Menu:
+
+* README::
+
+— The Detailed Node Listing —
+
+README
+
+* Installation::
+* Usage::
+* Dependencies::
+* Network compatibility::
+* Contributing::
+* Supporting ‘mastodon.el’: Supporting mastodonel.
+* Contributors::
+
+Installation
+
+* MELPA::
+* Emoji::
+* Discover::
+
+Usage
+
+* Logging in to your instance::
+* Timelines::
+* Composing toots::
+* Other commands and account settings::
+* Customization::
+* Alternative timeline layout::
+* Live-updating timelines mastodon-async-mode::
+* Translating toots::
+
+Timelines
+
+* Keybindings::
+* Toot byline legend::
+
+Composing toots
+
+* Keybindings: Keybindings (1).
+* Draft toots::
+
+Contributing
+
+* Bug reports::
+* Fixes and features::
+* Coding style::
+
+
+
+File: README.info,  Node: README,  Prev: Top,  Up: Top
+
+README
+******
+
+‘mastodon.el’ is an Emacs client for the AcitivityPub social networks
+that implement the Mastodon API.  For info see
+<https://joinmastodon.org/>.
+
+* Menu:
+
+* Installation::
+* Usage::
+* Dependencies::
+* Network compatibility::
+* Contributing::
+* Supporting ‘mastodon.el’: Supporting mastodonel.
+* Contributors::
+
+
+File: README.info,  Node: Installation,  Next: Usage,  Up: README
+
+Installation
+============
+
+Clone this repository and add the lisp directory to your load path.
+Then, require it and go.
+
+     (add-to-list 'load-path "/path/to/mastodon.el/lisp")
+     (require 'mastodon)
+
+   Or, with ‘use-package’:
+
+     (use-package mastodon
+       :ensure t)
+
+   The minimum Emacs version is now 27.1.  But if you are running an
+older version it shouldn’t be very hard to get it working.
+
+* Menu:
+
+* MELPA::
+* Emoji::
+* Discover::
+
+
+File: README.info,  Node: MELPA,  Next: Emoji,  Up: Installation
+
+MELPA
+-----
+
+Add ‘MELPA’ to your archives:
+
+     (require 'package)
+     (add-to-list 'package-archives
+                  '("melpa" . "http://melpa.org/packages/") t)
+
+   Update and install:
+
+   ‘M-x package-refresh-contents RET’
+
+   ‘M-x package-install RET mastodon RET’
+
+
+File: README.info,  Node: Emoji,  Next: Discover,  Prev: MELPA,  Up: Installation
+
+Emoji
+-----
+
+‘mastodon-mode’ will enable Emojify
+(https://github.com/iqbalansari/emacs-emojify) if it is loaded in your
+Emacs environment, so there’s no need to write your own hook anymore.
+‘emojify-mode’ is not required.
+
+
+File: README.info,  Node: Discover,  Prev: Emoji,  Up: Installation
+
+Discover
+--------
+
+‘mastodon-mode’ can provide a context menu for its keybindings if
+Discover (https://github.com/mickeynp/discover.el) is installed.  It is
+not required.
+
+   if you have Discover, add the following to your Emacs init
+configuration:
+
+     (require 'mastodon-discover)
+     (with-eval-after-load 'mastodon (mastodon-discover))
+
+   Or, with ‘use-package’:
+
+     (use-package mastodon
+       :ensure t
+       :config
+       (mastodon-discover))
+
+
+File: README.info,  Node: Usage,  Next: Dependencies,  Prev: Installation,  Up: README
+
+Usage
+=====
+
+* Menu:
+
+* Logging in to your instance::
+* Timelines::
+* Composing toots::
+* Other commands and account settings::
+* Customization::
+* Alternative timeline layout::
+* Live-updating timelines mastodon-async-mode::
+* Translating toots::
+
+
+File: README.info,  Node: Logging in to your instance,  Next: Timelines,  Up: Usage
+
+Logging in to your instance
+---------------------------
+
+You need to set 2 variables in your init file to get started:
+
+  1. ‘mastodon-instance-url’
+  2. ‘mastodon-active-user’
+
+   (see their doc strings for details).  For example If you want to post
+toots as “example_user@social.instance.org”, then put this in your init
+file:
+
+     (setq mastodon-instance-url "https://social.instance.org"
+           mastodon-active-user "example_user")
+
+   Then *restart* Emacs and run ‘M-x mastodon’.  Make sure you are
+connected to internet before you do this.  If you have multiple mastodon
+accounts you can activate one at a time by changing those two variables
+and restarting Emacs.
+
+   If you were using mastodon.el before 2FA was implemented and the
+above steps do not work, delete the old file specified by
+‘mastodon-client--token-file’ and restart Emacs and follow the steps
+again.
+
+
+File: README.info,  Node: Timelines,  Next: Composing toots,  Prev: Logging in to your instance,  Up: Usage
+
+Timelines
+---------
+
+‘M-x mastodon’
+
+   Opens a ‘*mastodon-home*’ buffer in the major mode and displays
+toots.  If your credentials are not yet saved, you will be prompted for
+email and password.  The app registration process will take place if
+your ‘mastodon-token-file’ does not contain ‘:client_id’ and
+‘:client_secret’.
+
+* Menu:
+
+* Keybindings::
+* Toot byline legend::
+
+
+File: README.info,  Node: Keybindings,  Next: Toot byline legend,  Up: Timelines
+
+Keybindings
+...........
+
+Key                      Action
+-----------------------------------------------------------------------------------------------------
+                         *Help*
+‘?’                      Show discover menu of all bindings, if ‘discover’ is available
+                         *Timeline actions*
+‘n’                      Go to next item (toot, notification)
+‘p’                      Go to previous item (toot, notification)
+‘M-n=/=<tab>’            Go to the next interesting thing that has an action
+‘M-p=/=<S-tab>’          Go to the previous interesting thing that has an action
+‘F’                      Open federated timeline
+‘H’                      Open home timeline
+‘L’                      Open local timeline
+‘N’                      Open notifications timeline
+‘@’                      Open mentions-only notifications timeline
+‘u’                      Update current timeline
+‘T’                      Open thread for toot at point
+‘#’                      Prompt for tag and open its timeline
+‘A’                      Open author profile of toot at point
+‘P’                      Open profile of user attached to toot at point
+‘O’                      View own profile
+‘U’                      update your profile bio note
+‘;’                      view instance description for toot at point
+‘,’                      view favouriters of toot at point
+‘.’                      view boosters of toot at point
+                         *Other views*
+‘S’                      search (posts, users, tags) (NB: only posts you have interacted with)
+‘I’, ‘c’, ‘d’            view, create, and delete filters
+‘R’, ‘a’, ‘j’            view/accept/reject follow requests
+‘G’                      view follow suggestions
+‘V’                      view your favourited toots
+‘K’                      view bookmarked toots
+‘X’                      view/edit/create/delete lists
+‘s’                      view your scheduled toots
+                         *Toot actions*
+‘t’                      Compose a new toot
+‘c’                      Toggle content warning content
+‘b’                      Boost toot under ‘point’
+‘f’                      Favourite toot under ‘point’
+‘k’                      toggle bookmark of toot at point
+‘r’                      Reply to toot under ‘point’
+‘v’                      Vote on poll at point
+‘C’                      copy url of toot at point
+‘C-RET’                  play video/gif at point (requires ‘mpv’)
+‘e’                      edit your toot at point
+‘E’                      view edits of toot at point
+‘i’                      (un)pin your toot at point
+‘d’                      delete your toot at point, and reload current timeline
+‘D’                      delete and redraft toot at point, preserving reply/CW/visibility
+(‘S-C-’) ‘W’, ‘M’, ‘B’   (un)follow, (un)mute, (un)block author of toot at point
+                         *Profile view*
+‘C-c C-c’                cycle between statuses, followers, following, and statuses without boosts
+                         ‘mastodon-profile--account-account-to-list’ (see lists view)
+                         *Notifications view*
+‘a’, ‘j’                 accept/reject follow request
+‘C-k’                    clear notification at point
+                         see ‘mastodon-notifications--get-*’ functions for filtered views
+                         *Quitting*
+‘q’                      Quit mastodon buffer, leave window open
+‘Q’                      Quit mastodon buffer and kill window
+‘C-M-q’                  Quit and kill all mastodon buffers
+
+
+File: README.info,  Node: Toot byline legend,  Prev: Keybindings,  Up: Timelines
+
+Toot byline legend
+..................
+
+Marker             Meaning
+--------------------------------------------
+‘(B)’              I boosted this toot
+‘(F)’              I favourited this toot
+‘(🔖)’ (or          I bookmarked this toot
+(‘K’))
+
+
+File: README.info,  Node: Composing toots,  Next: Other commands and account settings,  Prev: Timelines,  Up: Usage
+
+Composing toots
+---------------
+
+‘M-x mastodon-toot’ (or ‘t’ from a mastodon.el buffer).
+
+   Pops a new buffer/window in ‘mastodon-toot’ minor mode.  Enter the
+contents of your toot here.  ‘C-c C-c’ sends the toot.  ‘C-c C-k’
+cancels.  Both actions kill the buffer and window.
+
+   Autocompletion of mentions and tags is provided by
+‘completion-at-point-functions’ (capf) backends.
+‘mastodon-toot--enable-completion’ is enabled by default.  If you want
+to enable ‘company-mode’ in the toot compose buffer, set
+‘mastodon-toot--use-company-for-completion’ to ‘t’.  (‘mastodon.el’ used
+to run its own native company backends, but these have been removed in
+favour of capfs.)
+
+   Replies preserve visibility status/content warnings, and include
+boosters by default.
+
+   Server’s max toot length, and attachment previews, are shown.
+
+   You can download and use your instance’s custom emoji
+(‘mastodon-toot--download-custom-emoji’,
+‘mastodon-toot--enable-custom-emoji’).
+
+* Menu:
+
+* Keybindings: Keybindings (1).
+* Draft toots::
+
+
+File: README.info,  Node: Keybindings (1),  Next: Draft toots,  Up: Composing toots
+
+Keybindings
+...........
+
+Key         Action
+-------------------------------------------------
+‘C-c C-c’   Send toot
+‘C-c C-k’   Cancel toot
+‘C-c C-w’   Add content warning
+‘C-c C-v’   Change toot visibility
+‘C-c C-n’   Add sensitive media/nsfw flag
+‘C-c C-a’   Upload attachment(s)
+‘C-c !’     Remove all attachments
+‘C-c C-e’   Add emoji (if ‘emojify’ installed)
+‘C-c C-p’   Create a poll
+‘C-c C-l’   Set toot language
+
+
+File: README.info,  Node: Draft toots,  Prev: Keybindings (1),  Up: Composing toots
+
+Draft toots
+...........
+
+   • Compose buffer text is saved as you type, kept in
+     ‘mastodon-toot-current-toot-text’.
+   • ‘mastodon-toot--save-draft’: save the current toot as a draft.
+   • ‘mastodon-toot--open-draft-toot’: Open a compose buffer and insert
+     one of your draft toots.
+   • ‘mastodon-toot--delete-draft-toot’: Delete a draft toot.
+   • ‘mastodon-toot--delete-all-drafts’: Delete all your drafts.
+
+
+File: README.info,  Node: Other commands and account settings,  Next: Customization,  Prev: Composing toots,  Up: Usage
+
+Other commands and account settings:
+------------------------------------
+
+In addition to ‘mastodon’, the following three functions are autoloaded
+and should work without first loading ‘mastodon.el’:
+   • ‘mastodon-toot’: Compose new toot
+   • ‘mastodon-notifications-get’: View all notifications
+   • ‘mastodon-url-lookup’: Attempt to load a URL in ‘mastodon.el’.  URL
+     may be at point or provided in the minibuffer.
+
+   • ‘mastodon-tl--view-instance-description’: View information about
+     the instance that the author of the toot at point is on.
+   • ‘mastodon-tl--view-own-instance’: View information about your own
+     instance.
+   • ‘mastodon-search--trending-tags’: View a list of trending hashtags
+     on your instance.
+
+   • ‘mastodon-tl--add-toot-account-at-point-to-list’: Add the account
+     of the toot at point to a list.
+
+   • ‘mastodon-tl--follow-tag’: Follow a tag (works like following a
+     user)
+   • ‘mastodon-tl--unfollow-tag’: Unfollow a tag
+   • ‘mastodon-tl--list-followed-tags’: View a list of tags you’re
+     following.
+
+   • ‘mastodon-switch-to-buffer’: switch between mastodon buffers.
+
+   • ‘mastodon-profile--update-display-name’: Update the display name
+     for your account.
+   • ‘mastodon-profile--update-user-profile-note’: Update your bio note.
+   • ‘mastodon-profile--update-meta-fields’: Update your metadata
+     fields.
+   • ‘mastodon-profile--set-default-toot-visibility’: Set the default
+     visibility for your toots.
+   • ‘mastodon-profile--account-locked-toggle’: Toggle the locked status
+     of your account.  Locked accounts have to manually approve follow
+     requests.
+   • ‘mastodon-profile--account-discoverable-toggle’: Toggle the
+     discoverable status of your account.  Non-discoverable accounts are
+     not listed in the profile directory.
+   • ‘mastodon-profile--account-bot-toggle’: Toggle whether your account
+     is flagged as a bot.
+   • ‘mastodon-profile--account-sensitive-toggle’: Toggle whether your
+     posts are marked as sensitive (nsfw) by default.
+
+
+File: README.info,  Node: Customization,  Next: Alternative timeline layout,  Prev: Other commands and account settings,  Up: Usage
+
+Customization
+-------------
+
+See ‘M-x customize-group RET mastodon’ to view all customize options.
+
+   • Timeline options:
+        • Use proportional fonts
+        • Default number of posts displayed
+        • Timestamp format
+        • Relative timestamps
+        • Display user avatars
+        • Avatar image height
+        • Enable image caching
+        • Hide replies in timelines
+
+   • Compose options:
+        • Completion style for mentions and tags
+        • Enable custom emoji
+        • Display toot being replied to
+        • Set default reply visibility
+
+
+File: README.info,  Node: Alternative timeline layout,  Next: Live-updating timelines mastodon-async-mode,  Prev: Customization,  Up: Usage
+
+Alternative timeline layout
+---------------------------
+
+The incomparable Nicholas Rougier has written an alternative timeline
+layout for ‘mastodon.el’.
+
+   The repo is at <https://github.com/rougier/mastodon-alt>.
+
+
+File: README.info,  Node: Live-updating timelines mastodon-async-mode,  Next: Translating toots,  Prev: Alternative timeline layout,  Up: Usage
+
+Live-updating timelines: ‘mastodon-async-mode’
+----------------------------------------------
+
+(code taken from <https://github.com/alexjgriffith/mastodon-future.el>.)
+
+   Works for federated, local, and home timelines and for notifications.
+It’s a little touchy, one thing to avoid is trying to load a timeline
+more than once at a time.  It can go off the rails a bit, but it’s still
+pretty cool.  The current maintainer of ‘mastodon.el’ is unable to debug
+or improve this feature.
+
+   To enable, it, add ‘(require 'mastodon-async)’ to your ‘init.el’.
+Then you can view a timeline with one of the commands that begin with
+‘mastodon-async--stream-’.
+
+
+File: README.info,  Node: Translating toots,  Prev: Live-updating timelines mastodon-async-mode,  Up: Usage
+
+Translating toots
+-----------------
+
+You can translate toots with ‘mastodon-toot--translate-toot-text’ (‘a’
+in a timeline).  At the moment this requires lingva.el
+(https://codeberg.org/martianh/lingva.el), a little interface I wrote to
+<https://lingva.ml>, to be installed to work.
+
+   You could easily modify the simple function to use your Emacs
+translator of choice (‘libretrans.el’ , ‘google-translate’, ‘babel’,
+‘go-translate’, etc.), you just need to fetch the toot’s content with
+‘(mastodon-tl--content toot)’ and pass it to your translator function as
+its text argument.  Here’s what ‘mastodon-toot--translate-toot-text’
+looks like:
+
+     (defun mastodon-toot--translate-toot-text ()
+       "Translate text of toot at point.
+       Uses `lingva.el'."
+         (interactive)
+         (let* ((toot (mastodon-tl--property 'toot-json)))
+           (if toot
+               (lingva-translate nil (mastodon-tl--content toot))
+             (message "No toot to translate?"))))
+
+
+File: README.info,  Node: Dependencies,  Next: Network compatibility,  Prev: Usage,  Up: README
+
+Dependencies
+============
+
+Hard dependencies (should all install with ‘mastodon.el’):
+   • ‘request’ (for uploading attachments),
+     <https://github.com/tkf/emacs-request>
+   • ‘persist’ for storing some settings across sessions
+   • ‘ts’ for poll relative expiry times
+
+   Optional dependencies:
+   • ‘emojify’ for inserting and viewing emojis
+   • ‘mpv’ and ‘mpv.el’ for viewing videos and gifs
+   • ‘lingva.el’ for translating toots
+
+
+File: README.info,  Node: Network compatibility,  Next: Contributing,  Prev: Dependencies,  Up: README
+
+Network compatibility
+=====================
+
+‘mastodon.el’ should work with ActivityPub servers that implement the
+Mastodon API.
+
+   Apart from Mastodon itself, it is currently known to work with
+Pleroma and Gotosocial.  If you attempt to use ‘mastodon.el’ with
+another server that implements the Mastodon API and run into problems,
+feel free to open an issue.
+
+
+File: README.info,  Node: Contributing,  Next: Supporting mastodonel,  Prev: Network compatibility,  Up: README
+
+Contributing
+============
+
+PRs, issues, feature requests, and general feedback are very welcome!
+
+* Menu:
+
+* Bug reports::
+* Fixes and features::
+* Coding style::
+
+
+File: README.info,  Node: Bug reports,  Next: Fixes and features,  Up: Contributing
+
+Bug reports
+-----------
+
+  1. ‘mastodon.el’ has bugs, as well as lots of room for improvement.
+  2. I receive very little feedback, so if I don’t run into the bug it
+     often doesn’t get fixed.
+  3. If you run into something that seems broken, first try running
+     ‘mastodon.el’ in emacs with no init file (i.e.  ‘emacs -q’
+     (instructions and code for doing this are here
+     (https://codeberg.org/martianh/mastodon.el/issues/300)) to see if
+     it also happens independently of your own config (it probably
+     does).
+  4. Enable debug on error (‘toggle-debug-on-error’), make the bug
+     happen again, and copy the backtrace that appears.
+  5. Open an issue here and explain what is going on.  Provide your
+     emacs version and what kind of server your account is on.
+
+
+File: README.info,  Node: Fixes and features,  Next: Coding style,  Prev: Bug reports,  Up: Contributing
+
+Fixes and features
+------------------
+
+  1. Create an issue (https://codeberg.org/martianh/mastodon.el/issues)
+     detailing what you’d like to do.
+  2. Fork the repository and create a branch off of ‘develop’.
+  3. Run the tests and ensure that your code doesn’t break any of them.
+  4. Create a pull request referencing the issue created in step 1.
+
+
+File: README.info,  Node: Coding style,  Prev: Fixes and features,  Up: Contributing
+
+Coding style
+------------
+
+   • This library uses an unconvential double dash (‘--’) between file
+     namespaces and function names, which contradicts normal Elisp
+     style.  This needs to be respected until the whole library is
+     changed.
+   • Use ‘aggressive-indent-mode’ or similar to keep your code indented.
+   • Single spaces end sentences in docstrings.
+   • There’s no need for a blank line after the first docstring line
+     (one is added automatically when documentation is displayed).
+
+
+File: README.info,  Node: Supporting mastodonel,  Next: Contributors,  Prev: Contributing,  Up: README
+
+Supporting ‘mastodon.el’
+========================
+
+If you’d like to support continued development of ‘mastodon.el’, I
+accept donations via paypal: paypal.me/martianh
+(https://paypal.me/martianh).  If you would prefer a different payment
+method, write to me at that address and I can provide IBAN or other
+details.
+
+   I don’t have a tech worker’s income, so even a small tip would help
+out.
+
+
+File: README.info,  Node: Contributors,  Prev: Supporting mastodonel,  Up: README
+
+Contributors
+============
+
+‘mastodon.el’ is the work of a number of people.
+
+   Some significant contributors are:
+
+   • <https://github.com/jdenen> [original author]
+   • <http://atomized.org>
+   • <https://alexjgriffith.itch.io>
+   • <https://github.com/hdurer>
+   • <https://codeberg.org/Red_Starfish>
+
+
+
+Tag Table:
+Node: Top73
+Node: README828
+Node: Installation1221
+Node: MELPA1747
+Node: Emoji2101
+Node: Discover2419
+Node: Usage2957
+Node: Logging in to your instance3296
+Node: Timelines4283
+Node: Keybindings4788
+Node: Toot byline legend8697
+Node: Composing toots9042
+Node: Keybindings (1)10241
+Node: Draft toots10793
+Node: Other commands and account settings11328
+Node: Customization13617
+Node: Alternative timeline layout14351
+Node: Live-updating timelines mastodon-async-mode14714
+Node: Translating toots15536
+Node: Dependencies16661
+Node: Network compatibility17243
+Node: Contributing17719
+Node: Bug reports17998
+Node: Fixes and features18890
+Node: Coding style19359
+Node: Supporting mastodonel19969
+Node: Contributors20481
+
+End Tag Table
+
+
+Local Variables:
+coding: utf-8
+End: