Feed Commas User Manual

Feed Commas - user-friendly console CommaFeed client.

1. Introduction

Feed Commas is client application for CommaFeed, a Google Reader inspired self-hosted RSS reader. You don’t have to host your own instance of CommaFeed to use it. Free (gratis) accounts are available on https://commafeed.com and they work with Feed Commas as well.

Feed Commas is terminal application, but with a catchy, curses-based graphical frontend. It’s mainly navigated from keyboard; by default, it is configured with vim-like keybindings, but you can reconfigure it anyway you like. It’s intended audience are ordinary users who are not afraid of launching a console.

2. Installation

The easiest way to install Feed Commas is to use pip:

$ pip install --user feedcommas

If you downloaded Feed Commas source code directly, you can still easily install it quite easily by creating a developement virtualenv and symlinking Feed Commas executable. This method has additional benefit that pulling latest changes from git will auto-update your installation (unless dependencies change).

To use this method, you need installed python3-tox package:

$ cd feedcommas-git
$ tox -e dev
$ ln -s $(pwd)/.tox/dev/bin/feed-commas $HOME/.local/bin/feed-commas

2.1. Dependencies

Table 1. Feed Commas dependencies
Package	Version
`python3`	>= 3.4
`python3-urwid`	>= 1.3.1
`python3-requests`	>= 2.13.0
`python3-bs4`	>= 4.5.3
`python3-mgcomm`	>= 0.1.0

Table 2. Feed Commas documentation dependencies
Package	Version
`asciidoctor`
`make`
`git`

3. Interface

 ▼ Menu                                                         Article list ▼
┌──────────────────────────────────────────────────────────────────────────────┐
│All                    │┌────────────────────────────────────────────────────┐│
│Starred                ││How to make `lynx` fast?   Mon, 5 mar 2017, 22:54:00││
│Daily read             ││                                                    ││
│  /r/commandline(1)    ││   Anyone care share their lynx config?             ││
│  Lorem ipsum          ││   For some reason, lynx on my computer cannot open ││
│  The Codist           ││websites instantly.                                 ││
│  Andrzej's C++ blog   ││                                                    ││
│  Ludic Linux          ││☐                          submitted by /u/blablabla││
│Comics                 │└────────────────────────────────────────────────────┘│
│  MonkeyUser           │┌────────────────────────────────────────────────────┐│
│  Geek&Poke            ││Lorem ipsum                     4 mar 2017, 12:48:00││
│  xkcd                 ││                                                    ││
│                       ││   Lorem ipsum dolor sit amet.                      ││
│                       ││                                                    ││
│                       ││★☑                                            author││
│                       │└────────────────────────────────────────────────────┘│
│:show-unread                                                                  │
└──────────────────────────────────────────────────────────────────────────────┘
 ▲ Commandline / message display

Above is example view of Feed Commas, drawn to fit 80 characters wide terminal. Interface resizes dynamically, so on modern displays you’ll encounter more free space.

Its two main parts are menu with subscribed feeds and categories on the left, and article list on the right. Feed Commas starts with a focus on article list. To switch between menu and article list, use h and l by default (see navigation part of configuration). To scroll menu and article list, use by default j and k.

There’s also a command line on the bottom of the screen. It’s accessible after pressing : key. To close it, press Esc or delete the whole typed text. To show completion hints press Tab during typing a command.

Command line is also shared for a display of messages from Feed Commas (like errors encountered when communicating with CommaFeed, synchronization progress etc.). If commandline is active (i.e. command is being typed in), messages are displayed aisde of it.

Configuration

Before you’ll be able to actually use Feed Commas, you need to at least configure credentials used to log into CommaFeed. See Configuration and server sections in particular for details.

3.1. Commands

Most of commands are bound to some key by default, but not all of them. All of them, however, are available to by used in a Commandline. All commands, beside navigation ones (nav-up, nav-down, nav-right and nav-left) are available. For a complete list, see keys subsection.

You don’t have to type the whole command. If only one command starts with a typed string, a correct command will be executed. No command is executed in case of ambiguity. For example, :q will work the same as :quit, but :toggle won’t run anything because there are two possible commands: toggle-read and toggle-star.

4. Configuration

Feed Commas can be configured by setting several options in a standard ini-style configuration file. The file is searched in a filesystem in a way described by XDG Base Directory Specification. In practice it means that for most users it will be located in ~/.config/feed-commas/config.ini. However, any of below files can be read if the none of the previous ones was found:

$XDG_CONFIG_HOME/feed-commas/config.ini. If $XDG_CONFIG_HOME is not set, it defaults to $HOME/.config.
any of $XDG_DATA_DIRS/feed-commas/config.ini. $XDG_DATA_DIRS is colon-separated list of directories to check. If it is not set, it defaults to /etc/xdg.

If configuration file is not found, Feed Commas will create one with default parameters filled in a first suitable directory ($XDG_CONFIG_HOME/feed-commas).

Before Feed Commas terminates, previously read configuration file is saved back to a filesystem.

4.1. Structure

INI files are made up of sections, and so is the one Feed Commas uses. Below is example (but not complete) of file, which has [server] and [keys] sections.

[server]
address = https://commafeed.com
workers = 2

[keys]
nav-up = k
nav-down = j

Server

[server] contains options for configuring access to CommaFeed server.

Table 3. Available options for [server] section
Option	Default value	Description
`address`	`https://commafeed.com`	Address of CommaFeed instance with which Feed Commas will communicate.
`username`		name used to login to CommaFeed instance.
`password`		Plain text password which will be used to login to CommaFeed. Due to security reasons, it is not recommended leave passwords as plain text in any configuration file. Use password-cmd instead, which will dynamically get needed password.
`password-cmd`		A command used to get password to login to CommaFeed. It takes precedence over password, even if the latter is set.
`workers`	`2`	Number of worker processes used to communicate with CommaFeed. If it is unset, workers will be spawned in a number equal to available CPU cores.

Keys

[keys] contains key mappings used in Feed Commas.

Table 4. Available options for [keys] section
Option	Default value	Description
`nav-up`	`k`	Navigates and scrolls up. It is used e.g. to navigate a menu and scroll article list.
`nav-down`	`j`	Navigates and scrolls down. It is used e.g. to navigate a menu and scroll article list.
`nav-right`	`l`	Navigates right. It is used e.g. to switch used panel from menu to article list.
`nav-right`	`h`	Navigates right. It is used e.g. to switch used panel from article list to menu.
`toggle-read`	`r`	Toggles between read and unread state for currently selected article.
`toggle-star`	`s`	Stars or unstars currently selected article.
`show-all`		Shows both unread and read entries.
`show-unread`		Shows only unread entries.
`refresh`	`F5`	Refreshes list of articles. Also clears a cache.
`sync`		Downloads all feeds and categories for offline read. Only works if cache if `cache-time` is enabled (i.e. is set to non-negative value).
`open-browser`	`ctrl+]`	Opens selected article in a default web browser. Refer to the documentation of your Operating System how to configure one. Usually setting `$BROWSER` environment variable should be sufficient.
`quit`	`q`	Quits Feed Commas.

Key values can contain modifiers, but they heavily depend on what keycodes terminal sends. For example, terminals usually won’t explicitly send shift, but uppercase letters instead (so instead of mapping shift+e, map E).

Any combination of ctrl and alt modifiers is available as c- and a- prefixes. Other keys are also available:

Table 5. Special keys
Key on keyboard	config.ini notation
`ctrl`	`c-`
`alt`	`a-`
`shift`	`s-`
`↑`	`up`
`↓`	`down`
`←`	`left`
`→`	`right`
`Enter`	`enter`
`Return`	`enter`
`Page Up`	`page up`
`Page Down`	`page down`
`F5`	`f5`
Examples
`ctrl`+`a`	`c-a`
`alt`+`a`	`a-a`
`ctrl`+`alt`+`←`	`c-a-left`
`alt`+`Enter`	`a-enter`

Non-character keys should be written lower-case! Instead of typing F5, type f5, page down, enter and so on.

Settings

[settings] section contains options affecting various behaviours of Feed Commas.

Table 6. Available options for [settings] section
Option	Default value	Description
`mark-read-time`	`2`	Time (in seconds) after which currently selected article will be marked as read. If set to 0, articles will be marked as read immediately. If set to -1, articles won’t be automatically marked as read. Usually it’s advised to be kept as positive integer, which will prevent marking articles as unread when scrolling through an article list.
`show-read`	`false`	If set to true, all articles will be shown on the article list. If set to false, only unread articles will be shown. Using `toggle-read` automatically changes this setting so after application restart, the last state is used.
`supported-colors`	`256`	Number of colors supported by terminal. Most terminals nowdays support at least 256 colors, so if things work for you, don’t change this setting. Valid values: 1, 16, 88, 256
`bright-bold`	`false`	Display bright colors as bold (some terminals work that way). Change it to true if you don’t see a difference when using bright colors.
`html-filter`	`builtin`	Method of filtering HTML in received entries so they’re readable. Can be either of the following: `builtin` - simple (and inaccurate) builtin filtering method. Quite fast and doesn’t need any additional dependencies. `none` or unset option - filtering is disabled and HTML is printed exactly as received any filter command - external command, which accepts HTML on its stdin and converts it to a readable output on its stdout. Some text-based browsers (lynx, elinks) support such mode. Make sure to read a tip about commands if you want to use this option.
`cache-time`	`0`	Time (in minutes) for which each request to CommaFeed will be cached. If not set or set to 0, caching is disabled.

html-filter commands usage

Both lynx and elinks work very well as html-filter. Keep in mind however that they can slow down obtaining entries a little because an external process must be started separately for each entry.

The best results are achieved when they are configured with a dump wide enough, so that Feed Commas can take care of line wrapping:

html-filter = elinks -dump -dump-width 500
html-filter = lynx -dump -width 500 -stdin

Colors

Different parts of Feed Commas can be colorized to your liking by setting different options in [colors] section. Default values are sensible, but the end-result depends on terminal’s color capabilities. Color can be empty, in which case

Table 7. Available options for [settings] section
Option	Default value	Affected elements
`article-title`	`yellow`	Color of article’s title.
`article-title-focus`	`light blue`	Color of currently selected article’s title.
`article-border-focus`	`light blue`	Color of currently selected article’s border.
`metadata`	`light gray`	Various meta data information: article’s publication date, article’s header, various indicators on articles list, number of unread articles in menu etc.
`menu-focus-fg`	`white`	Foreground color of currently selected menu item.
`menu-focus-bg`	`light blue`	Background color of currently selected menu item.
`menu-selected`	`dark gray`	Color of currently active feed or category.
`menu-line`	`dark gray`	Color of line separating menu and article list.
`error-fg`	`white`	Foreground color of errors displayed in commandline.
`error-bg`	`dark red`	Background color of errors displayed in commandline.

Monochrome, 16-, 88- and 256-color terminals are supported. As a color name you can use any of standard color values: black, dark red, dark green, brown, dark blue, dark magenta, dark cyan, light gray, dark gray, light red, light green, yellow, light blue, light magenta, light cyan, white. For terminals which support that, you can also use other notations:

#fcc: hex like HTML color;
g40: decimal value: 40% of gray
g#cc: hex value: 80% of gray
h255: color number 255

For different terminals colors are configured in different ways, but most often they’re defined in ~/.Xresources file. Consult your terminal’s documentation for details.

Apart from color name, you can specify some text attributes, which should be placed after comma. These attributes include bold, underline, blink and standout. Color value can be omitted, in which case a default foreground or background color for your terminal will be used.

Table 8. Color setting examples
Setting	Description
`dark gray`	Set color to "dark gray" standard color.
`#f00,bold`	Set font to bold red.
`bold`	Set font to bold. Default color will be used (depending on which option is set)

5. License

Feed Commas is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

Feed Commas is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with Feed Commas. If not, see http://www.gnu.org/licenses/.