README.md

   1 tt
   2 ==
   3 A more-unixy [twtxt](https://github.com/buckket/twtxt) client.
   4
   5 [![Build Status](https://travis-ci.org/xandkar/tt.svg?branch=master)](https://travis-ci.org/xandkar/tt)
   6
   7 Doesn't force you to maintain a master "following" file (the way Twitter does),
   8 but let's you point it to any follow-file every time it runs.
   9
  10 This means unlimited possibilities for ad-hoc, interesting filtering
  11 combinations. Especially when paired with
  12 [process substitution](https://en.wikipedia.org/wiki/Process_substitution).
  13
  14 ### long format (default)
  15 ![Screenshot](screenshot-long.jpg)
  16
  17 ### short format (CLI option: -s)
  18 ![Screenshot](screenshot-short.jpg)
  19
  20
  21 instructions
  22 ------------
  23
  24 ### requirements
  25
  26 #### manual
  27 [Racket](https://download.racket-lang.org/)
  28
  29 #### package manager
  30 - Void Linux: `xbps-install racket`
  31 - Debian: `apt install racket`
  32
  33 ### installation
  34 `make build && make install` will build and copy `tt` binary into
  35 `$PREFIX/bin`, where `$PREFIX` defaults to `$HOME`.
  36
  37 ### configuration
  38 Put your `<nick>` and `<uri>` into `~/.tt/me`. For example, mine is:
  39
  40 ```
  41 $ cat ~/.tt/me
  42 xandkar https://xandkar.net/twtxt.txt
  43 ```
  44 It will be used to fill the `User-Agent` header, so that others can tell you're
  45 reading their twtxts and perhaps read yours. This isn't strictly necessary and
  46 if omitted, you'll stay anonymous.
  47
  48 ### usage
  49
  50                 $ tt --help
  51                 tt [ <option> ... ] <command> [<args>] ...
  52                  where <option> is one of
  53                         -d, --debug : Enable debug log level.
  54
  55                  and <command> is one of
  56                  r, read     : Read the timeline (offline operation).
  57                  d, download : Download the timeline.
  58                  u, upload   : Upload your twtxt file (alias to execute ~/.tt/upload).
  59                  c, crawl    : Discover new peers mentioned by known peers (offline operation).
  60
  61                         --help, -h : Show this help
  62                         -- : Do not treat any remaining argument as a switch (at this level)
  63                  Multiple single-letter switches can be combined after one `-'; for
  64                         example: `-h-' is the same as `-h --'
  65
  66 #### download
  67 peers' feeds from the Internet:
  68
  69                 $ tt d -h
  70                 tt download [ <option> ... ] [<file-paths>] ...
  71                  where <option> is one of
  72                         -j <njobs>, --jobs <njobs> : Number of concurrent jobs.
  73                         --help, -h : Show this help
  74                         -- : Do not treat any remaining argument as a switch (at this level)
  75                  Multiple single-letter switches can be combined after one `-'; for
  76                         example: `-h-' is the same as `-h --'
  77
  78 #### read
  79 your timeline:
  80
  81                 $ tt r -h
  82                 tt read [ <option> ... ] [<file-paths>] ...
  83                  where <option> is one of
  84                         -r, --rev : Reverse displayed timeline order.
  85                 / -s, --short : Short output format
  86                 \ -l, --long : Long output format
  87                         --help, -h : Show this help
  88                         -- : Do not treat any remaining argument as a switch (at this level)
  89                  /|\ Brackets indicate mutually exclusive options.
  90                  Multiple single-letter switches can be combined after one `-'; for
  91                         example: `-h-' is the same as `-h --'
  92
  93 `FOLLOW-FILE` contains lines with space-separated nick and twtxt.txt URI, like:
  94
  95 ```
  96 xandkar https://xandkar.net/twtxt.txt
  97 ```
  98
  99 If omitted, `FOLLOW-FILE` defaults to `~/.tt/peers`.
 100
 101 #### other commands
 102
 103     tt <command> -h
 104
 105
 106 notes
 107 -----
 108
 109 ### LWW downloads
 110 Downloaded timelines are stored in `~/.tt/cache/objects/<URL_ENCODED_URL>`, but
 111 no attempt is made to preserve the previously-downloaded messages - each
 112 download overrites the previous. One of the implications is that authors can
 113 edit/delete history without you noticing.