jenny

README (9001B)

---

      _
     (_) ___ _ __  _ __  _   _
     | |/ _ \ '_ \| '_ \| | | |
     | |  __/ | | | | | | |_| |
    _/ |\___|_| |_|_| |_|\__, |
   |__/                  |___/
   https://uninformativ.de/git/jenny
   https://uninformativ.de/bugs.html
 
 
 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 
 
 jenny is a twtxt client. One core feature is that all twts are stored in
 a maildir which can be viewed using a programm like mutt.
 
 Supports the following Yarn.social extensions:
 
     https://twtxt.dev/exts/twt-hash.html
     https://twtxt.dev/exts/twt-subject.html
 
 The name "jenny" comes from "the spinning jenny", because, you know,
 you're working with yarn and threads and stuff:
 
     https://en.wikipedia.org/wiki/Spinning_jenny
 
 
 Installation
 ------------
 
 You need:
 
     - Python 3
         - dateutil
         - requests
 
 In general, the programs have only been tested on GNU/Linux. Patches for
 more portability are welcome!
 
 
 Configuration
 -------------
 
 You need a file called ~/.config/jenny/conf.json. A minimal example:
 
     {
         "maildir_target": "~/Mail/twt",
         "local_twtxt_dir": "~/web/my.server.com",
         "publish_command": "some-rsync-script"
     }
 
 (The program will prefer $XDG_CONFIG_HOME over a plain ~/.config.)
 
 `maildir_target` is the path to a local, pre-existing maildir
 directory (including the subdirectories "cur", "new", and "tmp"). All
 twts -- your own and those written by others -- will be stored here.
 
 You will probably run jenny on your workstation (as opposed to directly
 on your server). This means that we must transfer the files created in
 `local_twtxt_dir` to the server after writing entries. jenny cannot know
 how to do this, so you are expected to specify a custom script of your
 own to do this job. This is `publish_command`. (`publish_command` is
 optional.)
 
 Complete config reference:
 
     - `announce_me`: Unless you have set `announce_me` to `false` (the
       default is `true`), your identity will be announced to those other
       feeds when they are fetched. The flags `DONT_ANNOUNCE_ME` or
       `ANNOUNCE_ME` can be added to individual lines in your `follow`
       file to override that global setting.
     - `editor`: Defaults to $VISUAL, or $EDITOR if that is unset, or
       `vi` if both are unset. This command is run through `sh -c ...`.
       If present, a literal "{}" will be replaced with the filename
       (shell-quote), otherwise that path is simply appended.
     - `local_twtxt_dir` (REQUIRED): Path to directory where twtxt files
       will be stored.
     - `local_twtxt_filename_format`: Defaults to `twtxt{}.txt`. The `{}`
       will be replaced by an appropriate suffix when your feed gets
       rotated.
     - `maildir_target` (REQUIRED): Path to maildir directory.
     - `max_twts_per_rotation`: Once your main feed ("twtxt.txt") reaches
       this many twts, they will be moved to an Archive Feed. Defaults to
       1000. Set to 0 to disable feed rotation.
     - `mention_marker`: When someone mentions you in their twtxt file,
       jenny will put a marker in the mail's "Subject:" line. You can
       customize this by setting `mention_marker` to a string of your
       liking.
     - `publish_command`: Script to run to publish your twtxt file.
     - `subject_maxlen`: Truncate the `Subject:` line of mail headers to
       this many characters. Defaults to 0, i.e. no truncation.
     - `yarn_pods_for_discovery`: When using `--fetch-context` (see Alt+C
       in the mutt example), jenny will try to retrieve the missing twt
       from the original feeds. If that fails, it can try to retrieve the
       twt from some Yarn pods. `yarn_pods_for_discovery` is a list of
       strings, e.g.: `"yarn_pods_for_discovery": ["https://twtxt.net"]`.
 
 Also note that the filename will always be `jenny-posting.eml`. This
 allows you to configure your editor to behave differently just for
 twtxt postings, e.g. you can do this in Vim:
 
     au BufRead,BufNewFile jenny-posting.eml setl wrap tw=0 fo-=t nu
 
 Initially, you must create your "twtxt.txt" manually in
 `local_twtxt_dir`. jenny expects some metadata in that file:
 
     # nick       = my-name
     # url        = https://my.server.com/twtxt.txt
     # avatar     = https://my.server.com/avatar.png
     #
     # These are aliases:
     # nick_alias = my-old-name-that-I-no-longer-use
     # url        = gopher://my.server.com/0/twtxt.txt
     #
     2020-10-11T10:40:48+02:00	hello world
 
 It will read your own nickname and the URLs under which your twtxt is
 available. The "nick =" line will be used to detect mentions. The
 "nick =" line together with the first "url =" line will be used to
 construct the user agent, which identifies you to other users.
 
 If other feeds contain "nick =" metadata as well, jenny will show it.
 
 "nick_alias =" and multiple "url =" lines can be used when you're
 transitioning from one name/URL to another. jenny will use them all to
 detect mentions, but it will only ever advertise "nick =" and "url =" to
 other servers.
 
 (An "avatar =" line is optional and not used by jenny, but it's good
 practice and might be used by other implementations.)
 
 For each twt, it will create one file in the configured maildir. The
 idea is that you run this as a cron job to create pseudo mail files.
 (Either on your workstation or on a server.) The goal is to create a
 pseudo mailbox of twts, which you can read using something like
 mutt.
 
 To follow other people, create ~/.config/jenny/follow:
 
     buckket https://buckket.org/twtxt.txt
     dilbert https://twtxt.net/user/dilbert/twtxt.txt DONT_ANNOUNCE_ME
     movq    https://www.uninformativ.de/twtxt.txt    ANNOUNCE_ME
 
 HTTP, HTTPS, Gopher, and Gemini are supported.
 
 Note that other people will have no idea that you're following them if
 you turn off announcing.
 
 
 Running
 -------
 
 Run without arguments to compose a new twt:
 
     $ jenny
 
 To reply to an already existing twt, provide the mail file on stdin (for
 mutt integration, see below):
 
     $ cat ~/Mail/twt/cur/zvvdala:2,S | jenny
 
 In both these cases, `publish_command` will be run once you've left the
 editor. However, if you wish to cancel and not publish your new twt, you
 have three options:
 
     1. Save an empty twt.
     2. Quit the editor without ever saving anything to the file.
     3. Quit the editor with an exit code other than 0 (":cq!" in Vim).
 
 To edit your twtxt file, run one of the following (`publish_command`
 will be run after this):
 
     $ jenny -e
     $ jenny --edit
 
 To fetch new twts from all the feeds you're following, run either of
 those:
 
     $ jenny -f
     $ jenny --fetch
 
 jenny will take note when a feed was last retrieved. You can show this
 database by running:
 
     $ jenny -l
     $ jenny --last-seen
 
 Or show the dates of the last twt of each feed:
 
     $ jenny -L
     $ jenny --last-twt
 
 This allows you to spot dead feeds.
 
 
 mutt integration
 ----------------
 
 Here is a full configuration file for mutt:
 
     # Strictly necessary or highly recommended.
     set mbox_type = Maildir
     set sort = threads
     set sort_aux = date-sent
     set strict_threads = yes
 
     # Optional styling.
     color index yellow default ~P
     set index_format = "%Z│%-15.15F│%3M│%s %* │%[%Y-%m-%d %H:%M]"
 
     # To highlight messages sent by you.
     alternates cathy
 
     # Key binds for jenny: Alt+T to write a new twt, Alt+R to reply to
     # thread, Alt+F to reply in a forked thread. Alt+C tries to fetch a
     # missing root twt (see explanation below).
     macro index,pager <esc>T "<shell-escape> jenny<Enter>" "Write new twt"
     macro index,pager <esc>R "\
     <enter-command> set my_pipe_decode=\$pipe_decode nopipe_decode<Enter>\
     <pipe-message> jenny<Enter>\
     <enter-command> set pipe_decode=\$my_pipe_decode; unset my_pipe_decode<Enter>" \
     "Reply to current twt"
     macro index,pager <esc>F "\
     <enter-command> set my_pipe_decode=\$pipe_decode nopipe_decode<Enter>\
     <pipe-message> jenny -t<Enter>\
     <enter-command> set pipe_decode=\$my_pipe_decode; unset my_pipe_decode<Enter>" \
     "Reply to current twt (fork conversation)"
     macro index,pager <esc>C "\
     <enter-command> set my_pipe_decode=\$pipe_decode nopipe_decode<Enter>\
     <pipe-message> jenny -c<Enter>\
     <enter-command> set pipe_decode=\$my_pipe_decode; unset my_pipe_decode<Enter>" \
     "Try to fetch context of current twt, like a missing root twt"
 
 Regarding Alt+C: It is relatively common that you follow some user and
 that user posts a reply to someone else -- but you don't follow that
 other person. That results in a broken thread. This function tries to
 fetch just that one missing twt, without you having to follow the entire
 feed. (See also: `yarn_pods_for_discovery`.)
 
 If you don't want to change your existing mutt setup (or if you don't
 have one yet), you can save this to a new file and launch mutt like
 this:
 
     $ mutt -F ~/.muttrc-jenny -f ~/Mail/twt
 
 
 Running the tests
 -----------------
 
 You need pytest: https://docs.pytest.org/en/stable/index.html
 
 Just run:
 
     $ pytest tests/