README.md

   1 Jan Pona Mute
   2 =============
   3
   4 The name is Toki Pona and means "many friends".
   5
   6 This is a very simple command line client for Diaspora that helps me
   7 deal with my specific use-cases:
   8
   9 - I want to check Diaspora for new comment on my threads
  10 - I want to leave new comments on my threads
  11 - I want to delete comments I left by mistake
  12
  13 It's *very* limited but it's helping me get started using the
  14 [diaspy](https://github.com/marekjm/diaspy) Python library.
  15
  16 <!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-refresh-toc -->
  17 **Table of Contents**
  18
  19 - [Installation](#installation)
  20 - [Quickstart](#quickstart)
  21 - [Next Step](#next-step)
  22 - [Notes](#notes)
  23 - [Reference](#reference)
  24
  25 <!-- markdown-toc end -->
  26
  27 Installation
  28 ------------
  29
  30 We need the [diaspy](https://github.com/marekjm/diaspy) library.
  31 Sadly, I've run into a few issues and made some fixes. I contributed
  32 these back but just to be sure I recommend you install diaspy from my
  33 own repository. That's the one I use.
  34
  35 ```text
  36 $ git clone https://alexschroeder.ch/cgit/diaspy
  37 $ cd diaspy
  38 $ pip3 install .
  39 ```
  40
  41 Note that using `pip3 install diaspy` gets me a much older revision
  42 and things won't work at all. 🤷
  43
  44 You need to download `jan-pona-mute` as well, obviously:
  45
  46 ```text
  47 $ git clone https://alexschroeder.ch/cgit/jan-pona-mute
  48 ```
  49
  50 With that done, you should be able to run it:
  51
  52 ```text
  53 $ python3 jan-pona-mute/jan-pona-mute.py
  54 ```
  55
  56 Quickstart
  57 ----------
  58
  59 ```text
  60 $ python3 jan-pona-mute.py
  61 Welcome to Diaspora! Use the intro command for a quick introduction.
  62 Pager set: /usr/bin/fold
  63 > account kensanata@pluspora.com
  64 Username and pod set: kensanata@pluspora.com
  65 > password *secret*
  66 Password set
  67 > login
  68 Setting up a connection...
  69 Logging in...
  70 > notifications
  71  1. 2019-08-13T19:40:17.000Z Joe Doe has liked your post I've started writing...
  72  2. 2019-08-13T17:59:23.000Z Joe Doe commented on your post Please help me wi...
  73  3. 2019-08-13T17:03:45.000Z Jane Doe has liked your post I've started writin...
  74  4. 2019-08-13T15:02:50.000Z June Doe commented on your post I don't like Mon...
  75  5. 2019-08-13T14:48:51.000Z John Doe liked your post Monday again! What am I...
  76 Enter a number to select the notification.
  77 > 1
  78 2019-08-13T19:40:17.000Z Joe Doe has liked your post I've started writing...
  79 Loading...
  80
  81 I've started writing a Diaspora client for the command line. It's called Jan Pona
  82 Mute which means as much as "many friends" in English. It's written in Python and
  83 doesn't do much.
  84 > comments
  85 There are no comments on the selected post.
  86 > comment This is me leaving a comment.
  87 Comment posted
  88 > comments
  89
  90  1. 2019-08-13T20:04:35.000Z Alex Schroeder
  91
  92 Alex Schroeder (e3bd7110b2ee013620f200505608f9fe): This is me leaving a comment.
  93 > quit
  94 Be safe!
  95 ```
  96
  97 Next Step
  98 ---------
  99
 100 Use the `save` command to save the login information (including the
 101 password!) to an init file.
 102
 103 The init files searched are:
 104
 105 1. `~/.config/jan-pona-mute/login`
 106 2. `~/.jan-pona-mute.d/login`
 107 3. `~/.jan-pona-mute`
 108
 109 If one of them exists while starting up, that's the file that gets
 110 written. If none exists, the first one is going to be created by the
 111 `save` command.
 112
 113 Any further commands you put into the file are simple executed as if
 114 you were to type them every time you start the program. A simple
 115 change would be to add `notifications` as a command to the end of the
 116 file.
 117
 118 Notes
 119 -----
 120
 121 One thing I care about is editing comments with my favourite editor
 122 and previewing them. This works really well if you have
 123 [mdcat](https://github.com/lunaryorn/mdcat) as it renders Markdown.
 124 Here's the workflow:
 125
 126 1. check notifications
 127 2. pick a post
 128 3. show latest comments
 129 4. compose a note
 130 5. preview note
 131 6. leave a comment with that note
 132
 133 This is what it looks like, assuming your editor is `ed`:
 134
 135 ```text
 136 > notifications
 137 ...
 138 > 1
 139 ...
 140 > comments
 141 ...
 142 > note nice
 143 /home/alex/.config/jan-pona-mute/notes/nice: No such file or directory
 144 a
 145 OK, I like this. Thanks!
 146 .
 147 w
 148 25
 149 q
 150  1. nice
 151 Use 'edit' to create a note.
 152 > preview nice
 153 OK, I like this. Thanks!
 154 > comment nice
 155 ```
 156
 157 This is important: if you have a note matching the comment you're
 158 about to post, the comment is replaced with the note's content.
 159
 160 Reference
 161 ---------
 162
 163 So much is still in flux. Please use the `help` command to learn more.
 164
 165 * use **intro** if you want to skip reading the rest of this list 😅
 166
 167 * use **account**, **password**, and **login** to login into your
 168   account; use **save** to store these three commands in your init
 169   file
 170
 171 * use **shortcuts** to show the current shortcuts; use **shortcut** to
 172   define a new shortcut; these are good commands to add to your init
 173   file (the **save** command won't do this for you)
 174
 175 * use **notifications** to see the latest notifications, use
 176   **notifications reload** to update the list; this is also a good
 177   command to add to your init file
 178
 179 * use **home** to see your home stream, use **home reload** to update
 180   the list; use **home all** to see the full list; use **home 3** to
 181   see the last 3 items
 182
 183 * use **show** and a number to show the post a notification is
 184   referring to, or to choose a post from your home stream; use
 185   **next** and **previous** to move from item to item; this is how you
 186   select a post which allows you to use **comments** to show the
 187   comments for that post; use **comments 3** to see the last 3 items
 188
 189 * use **comment** to post a comment, use **post** to write a new post;
 190   if you use a number instead of a writing a text, the number refers
 191   to a note (see below)
 192
 193 * use **undo** to delete a comment or post after writing it; use
 194   **delete comment** or **delete post** to delete them at a later date
 195
 196 * use **edit** and a filename to write a note; use **notes** to list
 197   your notes; use **preview** to show a note; use **delete note** to
 198   delete a note
 199
 200 * use **editor** to set your favourite editor (or set the EDITOR
 201   environment variable); use **pager** to set your favourite page (or
 202   set the PAGER environment variable); consider installing
 203   [mdcat](https://github.com/lunaryorn/mdcat) and using it as your pager
 204
 205 * use **info** to review your settings
 206
 207 * use **quit** to end the program