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 @example
  42 $ cmd/download.sh feeds/blog.stargrave.org_russian_feed.atom
  43 $ ./feeds-download.zsh # to invoke parallel downloading of everything
  44 @end example
  45
  46 Probably you want to change its default @env{$PROXY} value. It uses
  47 @command{curl}, that is aware of @code{If-Modified-Since} and
  48 @code{ETag} headers, compressed content encodings and HTTP redirections.
  49 If you want to see verbose output, then set @env{FEEDER_CURL_VERBOSE=1}.
  50
  51 @item Parse your feeds
  52
  53 @example
  54 $ cmd/parse.sh feeds/blog.stargrave.org_russian_feed.atom
  55 $ ./feeds-parse.zsh # to parse all feeds in parallel
  56 @end example
  57
  58 @item Run Mutt
  59
  60 @example
  61 $ ./feeds-browse.zsh
  62 @end example
  63
  64 That will read all feeds titles and create @file{mutt.rc} sourceable
  65 configuration file with predefined helpers and @code{mailboxes}
  66 commands. Mutt will be started in mailboxes browser mode (I will skip
  67 many entries):
  68
  69 @verbatim
  70   1   N [  1|101] 2021-02-17 20:41 Cryptology ePrint Archive/
  71   3     [  0|  8] 2021-12-02 19:28 Thoughts/
  72  32     [  0|  8] 2021-02-17 19:32 apenwarr/
  73 101     [ 10| 50] 2021-02-14 13:40 Блог Stargrave на русском comments/
  74 102     [  0| 51] 2021-02-17 19:37 Блог Stargrave на русском/
  75 316     [  0| 44] 2021-02-17 19:33 Eaten By A Grue: Infocom, Text Adventures, and Interactive Fiction/
  76 @end verbatim
  77
  78 ePrint has new entries since last downloading/parsing. Stargrave's blog
  79 comments have nothing new, but still ten unread entries.
  80
  81 If we open "Eaten By A Grue" mailbox, then will see its entries:
  82
  83 @verbatim
  84    1     [2021-01-30 11:00] Zork Zero: The Revenge of Megaboz (0,8K)
  85    2     [2021-06-12 11:01] Journey: The Quest Begins (0,8K)
  86    3     [2021-04-28 11:00] Eaten By A Cruise (0,8K)
  87 [...]
  88 ---Mutt: feeds/monsterfeet.com_grue.rss [Nachr:44 60K]---
  89 @end verbatim
  90
  91 @item Press @code{q} to return to mailbox browser again
  92
  93 This is made for convenience, because you will often switch your
  94 mailboxes (feeds), but @code{q} quits Mutt by default.
  95
  96 @item Press @code{A} to mark all messages read
  97
  98 And again this is made for convenience. It will mark both new
  99 (@strong{N}) and old-but-unread (@strong{O}) messages as read. You will
 100 see left tag-marks near each message to understand what was touched.
 101
 102 @item Index your messages
 103
 104 @example
 105 $ ./feeds-index.sh
 106 @end example
 107
 108 That will create @file{mu/} and @file{search/} directories and run
 109 @command{mu index} indexing, that is safely can be done incrementally
 110 after each download/parse cycle.
 111
 112 @item Search something
 113
 114 Press @code{<F8>} in Mutt's index and enter your mu/Xapian search query.
 115 Let's search for articles mentioning
 116 @url{https://en.wikipedia.org/wiki/Planetfall, Planetfall} during
 117 2019-2021 period: @code{Planetfall date:2019..2021}. @command{mu} will
 118 create symbolic links in @file{search/} subdirectory to the message. Press
 119 @code{<F9>} to switch that mailbox:
 120
 121 @verbatim
 122    1 [2021-12-20 07:08] Missed Classic: Stationfall - When Food Dispensers Attack (The Adventurers Guild)
 123    2 [2021-11-20 04:52] Missed Classic 102: Stationfall - Introduction (1987) (The Adventurers Guild)
 124    3 [2021-11-19 17:54] Boffo Games (The Digital Antiquarian)
 125    4 [2021-10-30 23:05] Missed Classic 100: The Manhole (1988) (The Adventurers Guild)
 126    5 [2020-05-17 22:16] Round 04 Reveal (unWinnable State)
 127    6 [2020-05-16 22:29] Round 03 Reveal (unWinnable State)
 128    7 [2020-04-20 11:00] Planetfall (Eaten By A Grue: Infocom, Text Adventures, and Interactive Fiction)
 129    8 [2020-04-09 11:00] Beyond Zork (Eaten By A Grue: Infocom, Text Adventures, and Interactive Fiction)
 130 -%-Mutt: =search [Nachr:8 215K]---
 131 @end verbatim
 132
 133 Pay attention that there is different index format, lacking unnecessary
 134 message flags display and adding name of the feed in parenthesis.
 135
 136 @item Cleanup excess number of messages
 137
 138 @example
 139 $ ./feeds-clear.zsh
 140 @end example
 141
 142 That will remove all messages in all feeds @file{cur/} directory that is
 143 not first hundred of ones, ordered by @code{mtime}. Pay attention that
 144 @file{new/} directory is not touched, so you won't loose completely new
 145 and unread messages when you are on vacation and left @command{cron}-ed
 146 workers. @command{cmd/feed2mdir/feed2mdir} command by default has
 147 @option{-max-entries 100} option set.
 148
 149 @item If you want to clean download state
 150
 151 @example
 152 $ cmd/download-clean.sh feed/FEED
 153 @end example
 154
 155 @end table