From f73a282ba79fc0e9fdf074c7a65db33e69302e78 Mon Sep 17 00:00:00 2001 From: marty hiatt Date: Fri, 3 Mar 2023 16:05:24 +0100 Subject: add README.info --- README.info | 653 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 653 insertions(+) create mode 100644 README.info (limited to 'README.info') 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 +. + +* 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=/=’ Go to the next interesting thing that has an action +‘M-p=/=’ 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 . + + +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 .) + + 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 +, 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), + + • ‘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: + + • [original author] + • + • + • + • + + + +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: -- cgit v1.2.3