Expand docs on passwords for remote APIs

Specifically, add a worked example of how to use GPG with passwordeval,
and rewrite the whole section in a way that's (hopefully) easier to read
for non-programmers.

1 files changed, 45 insertions, 31 deletions

diff --git a/doc/chapter-password.txt b/doc/chapter-password.txt
index c1a8d435..d481e8d8 100644
--- a/doc/chapter-password.txt
+++ b/doc/chapter-password.txt
@@ -1,31 +1,45 @@
-When using external APIs for newsfeeds, the user has different options for how
-to provide the password to authenticate against the API.
-Instead of directly writing the password into the configuration file,
-the user can choose to provide a file containing the password or an external
-command that evaluates to the user's password.
-This is useful if the user wants to share the configuration file online or
-store the password in a password manager or the systems keyring.
-
-For example when using the <<_the_old_reader,API for "The Old Reader">>,
-newsboat will first check the <<oldreader-password,`oldreader-password`>> configuration variable,
-if this variable is set (meaning it's present and not empty),
-then its value will be used for authentication.
-If <<oldreader-password,`oldreader-password`>> is not set (meaning it's not present or it's empty)
-but the <<oldreader-passwordfile,`oldreader-passwordfile`>> configuration variable is set,
-then the first line of this file will be used as the password.
-This is, unless the file doesn't exist, is unreadable or its first line is empty,
-in those cases Newsboat will exit with an error.
-If <<oldreader-passwordfile,`oldreader-passwordfile`>> is not set but <<oldreader-passwordeval,`oldreader-passwordeval`>> is set,
-then the command will be evaluated and the first line of the result will be
-used as the password.
-This is, unless the first line of the result's string is empty,
-in those cases Newsboat will exit with an error.
-Newsboat will ignore the exit status of the command,
-however it will wait for the command to exit.
-The command's output to stderr will be ignored by Newsboat and forwarded to
-the user, the output to stdout on the other hand will never be printed.
-If neither <<oldreader-password,`oldreader-password`>>, <<oldreader-passwordfile,`oldreader-passwordfile`>> nor
-<<oldreader-passwordeval,`oldreader-passwordeval`>> are set, then Newsboat will ask for the user's
-password with an interactive prompt.
-The entered password will be used unless it is empty,
-in which case Newsboat will exit with an error.
+There are a number of ways to specify a password, each represented by
+a separate setting. Newsboat looks for settings in certain order, and uses the
+first one that it finds. The exact order is described below.
+
+Settings are prefixed by API names; e.g. `newsblur-password`,
+`feedhq-passwordeval`. All APIs support all the settings; when reading examples
+below, just mentally replace the prefix with the name of the remote API you
+use.
+
+The first setting Newsboat checks is `ttrss-password`. It should contain the
+password in plain text.
+
+The second setting Newsboat checks is `newsblur-passwordfile`. It should
+contain a path to a file; the first line of that file should contain the
+password in plain text. If the file doesn't exit, is unreadable, or its first
+line is empty, Newsboat will exit with an error.
+
+The third setting Newsboat checks is `oldreader-passwordeval`. It should
+contain a command that, when executed, will print out the password. If the
+first line of command's output is empty, or the command fails to execute,
+Newsboat will exit with an error. This is the most versatile of all the
+options, because it lets you emulate every other and more; let's look at it in
+more detail.
+
+For example, a user might want to store their password in a file encrypted by
+GPG. They create the file like that:
+
+    $ gpg --encrypt --default-recipient-self --output ~/.newsboat/password.gpg
+
+They enter their password, press Enter, and finish the command by pressing ^D
+(Control and d simultaneously). Then, they specify in their Newsboat config:
+
+    feedhq-passwordeval "gpg --decrypt ~/.newsboat/password.gpg"
+
+Now every time they start Newsboat, GPG will be ran. It'll probably ask for
+keyring password, then decrypt the file, and pass its contents to Newsboat,
+which will use it to authenticate with the remote API.
+
+The user might use any other command here; for example, they could fetch the
+password from GNOME keyring, KeePass, or somewhere else entirely. The
+possibilities are truly endless.
+
+If no of the aforementioned settings were found, Newsboat will ask the user for
+the password using an interactive prompt. If the password that user enters is
+empty, Newsboat will give up and exit with an error.