doc/usage.texi

   1 @node Usage
   2 @unnumbered Usage
   3
   4 How @strong{I} use it:
   5
   6 @table @asis
   7
   8 @item Get its source code
   9
  10 @example
  11 $ git clone git://git.stargrave.org/feeder.git
  12 $ cd feeder
  13 @end example
  14
  15 @item Compile @command{feed2mdir} utility
  16
  17 @example
  18 $ ( cd cmd/feed2mdir ; go build )
  19 @end example
  20
  21 @item Create feeds state directories
  22
  23 You can create feeds subdirectories under @file{feeds/} manually:
  24
  25 @example
  26 $ mkdir -p feeds/my_first_feed/@{cur,new,tmp@}
  27 $ echo http://example.com/feed.atom > feeds/my_first_feed/url
  28 @end example
  29
  30 or convert Newsboat @file{urls} file (containing many lines with URLs)
  31 with @file{urls2feeds.zsh} to subdirectories hierarchy:
  32
  33 @example
  34 $ ./urls2feeds.zsh < ~/.newsboat/urls
  35 $ cat feeds/blog.stargrave.org_russian_feed.atom/url
  36 http://blog.stargrave.org/russian/feed.atom
  37 @end example
  38
  39 @item Download your feed(s) data
  40
  41 Downloading is implemented in @command{redo}'s
  42 @file{default.download.do} file. Probably you want to change its default
  43 @env{$PROXY} value. It uses @command{curl}, that is aware of
  44 @code{If-Modified-Since} and @code{ETag} headers, compressed content
  45 encodings and HTTP redirections.
  46
  47 You can invoke feed downloading like that:
  48
  49 @example
  50 $ redo feeds/blog.stargrave.org_russian_feed.atom/feed.download
  51 @end example
  52
  53 If you want to see verbose output, then set @env{FEEDER_CURL_VERBOSE=1}.
  54
  55 As a rule, you wish to run all feeds downloading in parallel. You can
  56 use @file{feeds-download.zsh}, that just invokes @command{redo-ifchange}
  57 with @option{-f} option (forceful rebuild). Why that? Because most
  58 @command{redo} implementations (that forces target building) do not
  59 parallelize specified targets build. But you can also use @command{parallel}:
  60
  61 @example
  62 $ parallel "redo @{@}/feed.download" ::: feeds/*
  63 @end example
  64
  65 @item Parse your feeds
  66
  67 Parsing (and Maildir filling) is implemented in @command{redo}'s
  68 @file{default.parse.do} file. It calls @command{cmd/feed2mdir/feed2mdir}
  69 utility, that read @file{feeds/FEED/feed} from stdin, takes Maildir
  70 directory as its first argument and prints feed's title.
  71
  72 You can use @file{feeds-parse.zsh} helper or invoke @command{parallel}
  73 as in example above, replacing @code{.download} with @code{.parse}.
  74
  75 @example
  76 $ ./feeds-parse.zsh
  77 @end example
  78
  79 @item Run Mutt
  80
  81 @example
  82 $ ./feeds-browse.zsh
  83 @end example
  84
  85 That will read all feeds titles and create @file{mutt.rc} sourceable
  86 configuration file with predefined helpers and @code{mailboxes}
  87 commands. Mutt will be started in mailboxes browser mode (I will skip
  88 many entries):
  89
  90 @verbatim
  91   1   N [  1|101] 2021-02-17 20:41 Cryptology ePrint Archive/
  92   3     [  0|  8] 2021-12-02 19:28 Thoughts/
  93  32     [  0|  8] 2021-02-17 19:32 apenwarr/
  94 101     [ 10| 50] 2021-02-14 13:40 Блог Stargrave на русском comments/
  95 102     [  0| 51] 2021-02-17 19:37 Блог Stargrave на русском/
  96 316     [  0| 44] 2021-02-17 19:33 Eaten By A Grue: Infocom, Text Adventures, and Interactive Fiction/
  97 @end verbatim
  98
  99 ePrint has new entries since last downloading/parsing. Stargrave's blog
 100 comments have nothing new, but still ten unread entries.
 101
 102 If we open "Eaten By A Grue" mailbox, then will see its entries:
 103
 104 @verbatim
 105    1     [2021-01-30 11:00] Zork Zero: The Revenge of Megaboz (0,8K)
 106    2     [2021-06-12 11:01] Journey: The Quest Begins (0,8K)
 107    3     [2021-04-28 11:00] Eaten By A Cruise (0,8K)
 108 [...]
 109 ---Mutt: feeds/monsterfeet.com_grue.rss [Nachr:44 60K]---
 110 @end verbatim
 111
 112 @item Press @code{q} to return to mailbox browser again
 113
 114 This is made for convenience, because you will often switch your
 115 mailboxes (feeds), but @code{q} quits Mutt by default.
 116
 117 @item Press @code{A} to mark all messages read
 118
 119 And again this is made for convenience. It will mark both new
 120 (@strong{N}) and old-but-unread (@strong{O}) messages as read. You will
 121 see left tag-marks near each message to understand what was touched.
 122
 123 @item Index your messages
 124
 125 @example
 126 $ ./feeds-index.sh
 127 @end example
 128
 129 That will create @file{mu/} and @file{search/} directories and run
 130 @command{mu index} indexing, that is safely can be done incrementally
 131 after each download/parse cycle.
 132
 133 @item Search something
 134
 135 Press @code{<F8>} in Mutt's index and enter your mu/Xapian search query.
 136 Let's search for articles mentioning
 137 @url{https://en.wikipedia.org/wiki/Planetfall, Planetfall} during
 138 2019-2021 period: @code{Planetfall date:2019..2021}. @command{mu} will
 139 create symbolic links in @file{search/} subdirectory to the message. Press
 140 @code{<F9>} to switch that mailbox:
 141
 142 @verbatim
 143    1 [2021-12-20 07:08] Missed Classic: Stationfall - When Food Dispensers Attack (The Adventurers Guild)
 144    2 [2021-11-20 04:52] Missed Classic 102: Stationfall - Introduction (1987) (The Adventurers Guild)
 145    3 [2021-11-19 17:54] Boffo Games (The Digital Antiquarian)
 146    4 [2021-10-30 23:05] Missed Classic 100: The Manhole (1988) (The Adventurers Guild)
 147    5 [2020-05-17 22:16] Round 04 Reveal (unWinnable State)
 148    6 [2020-05-16 22:29] Round 03 Reveal (unWinnable State)
 149    7 [2020-04-20 11:00] Planetfall (Eaten By A Grue: Infocom, Text Adventures, and Interactive Fiction)
 150    8 [2020-04-09 11:00] Beyond Zork (Eaten By A Grue: Infocom, Text Adventures, and Interactive Fiction)
 151 -%-Mutt: =search [Nachr:8 215K]---
 152 @end verbatim
 153
 154 Pay attention that there is different index format, lacking unnecessary
 155 message flags display and adding name of the feed in parenthesis.
 156
 157 @item Cleanup excess number of messages
 158
 159 @example
 160 $ ./feeds-clear.zsh
 161 @end example
 162
 163 That will remove all messages in all feeds @file{cur/} directory that is
 164 not first hundred of ones, ordered by @code{mtime}. Pay attention that
 165 @file{new/} directory is not touched, so you won't loose completely new
 166 and unread messages when you are on vacation and left @command{cron}-ed
 167 workers. @command{cmd/feed2mdir/feed2mdir} command by default has
 168 @option{-max-entries 100} option set.
 169
 170 @item If you want to clean download state
 171
 172 @example
 173 $ redo feeds/FEED/feed.clean
 174 @end example
 175
 176 @end table