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 @command{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 @command{urls2feeds.zsh} won't touch already existing directories and will
  40 warn if some of them disappeared from @file{urls}.
  41
  42 @item Download your feed(s) data
  43
  44 @example
  45 $ cmd/download.sh feeds/blog.stargrave.org_russian_feed.atom
  46 $ ./feeds-download.zsh # to invoke parallel downloading of everything
  47 @end example
  48
  49 Probably you want to change its default @env{$PROXY} value. It uses
  50 @command{curl}, that is aware of @code{If-Modified-Since} and
  51 @code{ETag} headers, compressed content encodings and HTTP redirections.
  52 If you want to see verbose output, then set @env{FEEDER_CURL_VERBOSE=1}.
  53
  54 @item Parse your feeds
  55
  56 @example
  57 $ cmd/parse.sh feeds/blog.stargrave.org_russian_feed.atom
  58 $ ./feeds-parse.zsh # to parse all feeds in parallel
  59 @end example
  60
  61 @item Quick overview of the news:
  62
  63 @example
  64 $ ./feeds-news.zsh
  65 habr.com_ru_rss_interesting: 7
  66 habr.com_ru_rss_news: 3
  67 lobste.rs_rss: 3
  68 naked-science.ru_?yandex_feed=news: 1
  69 planet.fsfe.org_atom.xml: 1
  70 www.astronews.ru_astronews.xml: 1
  71 www.darkside.ru_news_rss: 5
  72 @end example
  73
  74 @item Run Mutt
  75
  76 @example
  77 $ ./feeds-browse.zsh
  78 @end example
  79
  80 That will read all feeds titles and create @file{mutt.rc} sourceable
  81 configuration file with predefined helpers and @code{mailboxes}
  82 commands. Mutt will be started in mailboxes browser mode (I will skip
  83 many entries):
  84
  85 @verbatim
  86   1   N [  1|101] 2021-02-17 20:41 Cryptology ePrint Archive/
  87   3     [  0|  8] 2021-12-02 19:28 Thoughts/
  88  32     [  0|  8] 2021-02-17 19:32 apenwarr/
  89 101     [ 10| 50] 2021-02-14 13:40 Блог Stargrave на русском comments/
  90 102     [  0| 51] 2021-02-17 19:37 Блог Stargrave на русском/
  91 316     [  0| 44] 2021-02-17 19:33 Eaten By A Grue: Infocom, Text Adventures, and Interactive Fiction/
  92 @end verbatim
  93
  94 ePrint has new entries since last downloading/parsing. Stargrave's blog
  95 comments have nothing new, but still ten unread entries.
  96
  97 If we open "Eaten By A Grue" mailbox, then will see its entries:
  98
  99 @verbatim
 100    1     [2021-01-30 11:00] Zork Zero: The Revenge of Megaboz (0,8K)
 101    2     [2021-06-12 11:01] Journey: The Quest Begins (0,8K)
 102    3     [2021-04-28 11:00] Eaten By A Cruise (0,8K)
 103 [...]
 104 ---Mutt: feeds/monsterfeet.com_grue.rss [Nachr:44 60K]---
 105 @end verbatim
 106
 107 @item Press @code{q} to return to mailbox browser again
 108
 109 This is made for convenience, because you will often switch your
 110 mailboxes (feeds), but @code{q} quits Mutt by default.
 111
 112 @item Press @code{A} to mark all messages read
 113
 114 And again this is made for convenience. It will mark both new
 115 (@strong{N}) and old-but-unread (@strong{O}) messages as read. You will
 116 see left tag-marks near each message to understand what was touched.
 117
 118 @item Press @code{o} to open links and enclosures URLs
 119
 120 Do it in pager mode and you message will be piped to
 121 @command{cmd/x-urlview.sh}, that will show all @code{X-URL}
 122 and @code{X-Enclosure} links.
 123
 124 @item Index your messages
 125
 126 @example
 127 $ ./feeds-index.sh
 128 @end example
 129
 130 That will create @file{mu/} and @file{search/} directories and run
 131 @command{mu index} indexing, that is safely can be done incrementally
 132 after each download/parse cycle.
 133
 134 @item Search something
 135
 136 Press @code{<F8>} in Mutt's index and enter your mu/Xapian search query.
 137 Let's search for articles mentioning
 138 @url{https://en.wikipedia.org/wiki/Planetfall, Planetfall} during
 139 2019-2021 period: @code{Planetfall date:2019..2021}. @command{mu} will
 140 create symbolic links in @file{search/} subdirectory to the message. Press
 141 @code{<F9>} to switch that mailbox:
 142
 143 @verbatim
 144    1 [2021-12-20 07:08] Missed Classic: Stationfall - When Food Dispensers Attack (The Adventurers Guild)
 145    2 [2021-11-20 04:52] Missed Classic 102: Stationfall - Introduction (1987) (The Adventurers Guild)
 146    3 [2021-11-19 17:54] Boffo Games (The Digital Antiquarian)
 147    4 [2021-10-30 23:05] Missed Classic 100: The Manhole (1988) (The Adventurers Guild)
 148    5 [2020-05-17 22:16] Round 04 Reveal (unWinnable State)
 149    6 [2020-05-16 22:29] Round 03 Reveal (unWinnable State)
 150    7 [2020-04-20 11:00] Planetfall (Eaten By A Grue: Infocom, Text Adventures, and Interactive Fiction)
 151    8 [2020-04-09 11:00] Beyond Zork (Eaten By A Grue: Infocom, Text Adventures, and Interactive Fiction)
 152 -%-Mutt: =search [Nachr:8 215K]---
 153 @end verbatim
 154
 155 Pay attention that there is different index format, lacking unnecessary
 156 message flags display and adding name of the feed in parenthesis.
 157
 158 @item Cleanup excess number of messages
 159
 160 @example
 161 $ ./feeds-clear.zsh
 162 @end example
 163
 164 That will remove all messages in all feeds @file{cur/} directory that is
 165 not first hundred of ones, ordered by @code{mtime}. Pay attention that
 166 @file{new/} directory is not touched, so you won't loose completely new
 167 and unread messages when you are on vacation and left @command{cron}-ed
 168 workers. @command{cmd/feed2mdir/feed2mdir} command by default has
 169 @option{-max-entries 100} option set.
 170
 171 @item If you want to clean download state
 172
 173 @example
 174 $ cmd/download-clean.sh feed/FEED
 175 @end example
 176
 177 @anchor{Enclosures}
 178 @item Download enclosures
 179
 180 Many feeds include links to so-called enclosures, like audio files for
 181 podcasts. While you mail is not processed by MUA, its @file{new/}
 182 messages still there, you can run enclosure downloading process, that
 183 uses @url{https://www.gnu.org/software/wget/, GNU Wget}. Specify the
 184 directory where your enclosures should be placed. Each enclosure's
 185 filename is more or less filesystem-friendly with the current timestamp
 186 in it.
 187
 188 @example
 189 $ mkdir path/to/enclosures
 190 $ ./feeds-encs.zsh path/to/enclosures
 191 [...]
 192 traffic.libsyn.com_monsterfeet_grue_018.mp3-20220218-152822
 193 [...]
 194 $ file path/to/enclosures/traffic.libsyn.com_monsterfeet_grue_018.mp3-20220218-152822
 195 path/to/...: Audio file with ID3 version 2.2.0, contains:MPEG ADTS, layer III, v1,  96 kbps, 44.1 kHz, Monaural
 196 @end example
 197
 198 @command{feeds-encs.zsh} do not parallelize jobs, because enclosure are
 199 often heavy enough to satiate your Internet link.
 200
 201 @end table