Add proper documentation.

AUTHORS

@@ -0,0 +1,2 @@
+Bennett Piater
+Justus Piater

Makefile

@@ -3,15 +3,17 @@ PREFIX ?= /usr/local
 SHRDIR ?= $(DESTDIR)$(PREFIX)/share
 BINDIR ?= $(DESTDIR)$(PREFIX)/bin
 
-.PHONY: install
+all: man1/puma.1 man1/puma-add.1 man7/puma.7
 
-install:
+.PHONY: install all
+
+install: all
 	@install -Dm755 bin/*	       -t $(BINDIR)
-	@install -Dm644 cmp/zsh/*      -t $(SHRDIR)/zsh/site-functions
-	@install -Dm644 man1/*	       -t $(SHRDIR)/man/man1
-	@install -Dm644 man7/*	       -t $(SHRDIR)/man/man7
+#	@install -Dm644 cmp/zsh/*      -t $(SHRDIR)/zsh/site-functions
+	@install -Dm644 man1/*.1	   -t $(SHRDIR)/man/man1
+	@install -Dm644 man7/*.7	   -t $(SHRDIR)/man/man7
 	@install -Dm644 LICENSE	       -t $(SHRDIR)/licenses/$(PROGNM)
-	#@install -Dm644 THANKS README  -t $(SHRDIR)/doc/$(PROGNM)
+#	@install -Dm644 THANKS README  -t $(SHRDIR)/doc/$(PROGNM)
 
 man1/%.1: man1/%.1.md
 	pandoc -s -t man $< > $@

README.md

@@ -30,8 +30,9 @@ Optionally, for `puma-menu`:
 Optionally, for `puma-add`:
 
 - `zenity`
+- `diceware` for secure random password generation
 
-To install, just type `make install` in the project root. The Makefile honors the `PREFIX` and `DESTDIR` environment variables for easy packaging by maintainers used to autotools.
+To install, just type `make install` in the project root. The Makefile honors the `PREFIX` and `DESTDIR` environment variables for easy packaging by maintainers used to the GNU autotools.
 
 ## Usage
 To type out the user name, TAB, password and ENTER for an account:
@@ -40,10 +41,14 @@ To type out the user name, TAB, password and ENTER for an account:
     $puma -u <account-name>  # Types the user name only
     $puma -p <account-name>  # Types the password only
 
-`puma-add` is a GUI dialog to simplify adding an account:
-
-    $puma-add [--random]
+You will probably only use `puma` directly in your own scripts, or if using a window manager like AwesomeWM that allows you to execute arbitrary shell commands.
 
 `puma-menu` uses `dmenu` to provide a GUI login flow. This is the recommended way to use PUMA.
 
 Simply invoke it with keyboard focus in a login form and select the account to which you want to be logged in.
+
+`puma-add` is a GUI dialog to simplify adding an account:
+
+    $puma-add [--random]
+
+For more information, read the man-pages.

bin/puma

@@ -1,4 +1,5 @@
-#!/bin/sh
+#!/bin/bash
+# Log in using credentials
 #
 # This file is part of PUMA.
 # Copyright 2017 Bennett Piater and Justus Piater
@@ -25,7 +26,7 @@
 # Starting from the current X cursor position, this script then types
 # <username> <TAB> <password> <ENTER>
 
-keyring=$HOME/Documents/keyring
+PUMA_KEYRING="${PUMA_KEYRING:-$HOME/Documents/keyring}"
 
 u=yes
 p=yes
@@ -37,10 +38,26 @@ while test $# -gt 0; do
     esac
 done
 
+if [[ x"$key" = x ]]; then
+    echo "usage: $0 [-u|-p] <account>" >&2
+    exit 1
+elif [[ x"$key" = x"--help" || x"$key" = x"-h" ]]; then
+    echo "usage: $0 [-u|-p] <account>
+
+Type out user name, TAB, password and ENTER.
+
+<account> is the file name without .gpg.
+Options:
+ -u    only type the user name + TAB.
+ -p    only type the password + ENTER.
+"
+    exit 0
+fi
+
 
 typeout() {
     local gpg="/usr/bin/gpg --no-tty --quiet --decrypt $keyring/$key.gpg"
-    echo type $($gpg | grep -m 1 "$1: " | cut -d " " -f 2) | xdotool -
+    echo type "$($gpg | grep -m 1 "$1: " | cut -d " " -f 2)" | xdotool -
 }
 
 

bin/puma-add

@@ -1,4 +1,5 @@
 #!/bin/bash
+# Script to simplify adding a new user/pass combination
 #
 # This file is part of PUMA.
 # Copyright 2017 Bennett Piater and Justus Piater
@@ -16,10 +17,13 @@
 # You should have received a copy of the GNU General Public License
 # along with PUMA.  If not, see <http://www.gnu.org/licenses/>.
 
+#PUMA_GPGID="${PUMA_GPGID:[email protected]}"
+PUMA_KEYRING="${PUMA_KEYRING:-$HOME/Documents/keyring}"
+
 if [[ x"$1" = x"--random" ]]; then
 	IFS="|" read -r FNAME USER < <(zenity --title "Add a new user" --forms --text="Add a new user with random password" --add-entry=filename --add-entry=user)
-	PASS=$(diceware)
-	printf "%s" "$PASS" | xclip  # Copy the randomly-generated password to the clipboard
+	PASS=$(diceware) || exit 1
+	#printf "%s" "$PASS" | xclip  # Copy the randomly-generated password to the clipboard
 else
 	IFS="|" read -r FNAME USER PASS < <(zenity --title "Add a new user" --forms --text="Add a new user" --add-entry=filename --add-entry=user --add-password=pass)
 fi
@@ -29,11 +33,10 @@ if [[ -z "$FNAME" || -z "$USER" || -z "$PASS" ]]; then
 	exit 1
 fi
 
-FILENAME="$HOME"/Documents/keyring/"$FNAME"
-
-printf "User: %s\nPass: %s\n" "$USER" "$PASS" >"$FILENAME"
+FILENAME="$PUMA_KEYRING"/"$FNAME"
 
-gpg --batch --yes --encrypt --recipient [email protected] "$FILENAME" || zenity --error --text "gpg error!"
+cat <<< "User: $USER"$'\n'"Pass: $PASS"$'\n' >"$FILENAME"
+gpg --batch --yes --encrypt --recipient "$PUMA_GPGID" "$FILENAME" || { zenity --error --text "gpg error!"; exit 1; }
 
 rm -f "$FILENAME"
 

bin/puma-menu

@@ -1,4 +1,5 @@
 #! /bin/sh
+# Wrapper providing a log-in GUI
 #
 # This file is part of PUMA.
 # Copyright 2017 Bennett Piater and Justus Piater
@@ -20,4 +21,6 @@
 # If you do so, invoke this and simply select the account that you want to use.
 # (While having focus in a login form) The up script will then log you in.
 
-ls -1B ~/Documents/keyring | sed 's/\(.*\)\..*/\1/' | dmenu -p "Login:" | xargs ~/bin/up
+PUMA_KEYRING="${PUMA_KEYRING:-$HOME/Documents/keyring}"
+
+ls -1B "$HOME/$PUMA_KEYRING" | sed 's/\(.*\)\..*/\1/' | dmenu -p "Login:" | xargs ~/bin/up

man1/puma-add.1.md

@@ -0,0 +1,50 @@
+% PUMA-ADD(1) PUMA user manuals
+% Bennett Piater and Justus Piater
+% January 07, 2017
+
+# NAME
+puma-add - Add a user account to PUMA
+
+# SYNOPSIS
+puma-add [*options*]
+
+# Description
+Helper script to simplify the flow of adding a new account to PUMA.
+
+It shows a zenity form popup into which one can enter the account name, user name and password, writes the file, and encrypts it.
+
+The password is shown in a popup at the end so it can easily be copied.
+
+# OPTIONS
+--random
+: Generate a random password instead of asking for it in the popup.
+
+# EXIT STATUS
+TODO
+
+# ENVIRONMENT
+PUMA_KEYRING
+: The folder containing the credential files. Defaults to *~/Documents/keyring*.
+
+PUMA_GPGID
+: The gpg id with which to encrypt the password files.
+
+# NOTES
+
+# BUGS
+
+# SEE ALSO
+**puma**(1), **puma**(7)
+
+# COPYRIGHT
+PUMA 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.
+PUMA 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 PUMA.  If not, see <http://www.gnu.org/licenses/>.

man1/puma.1.md

@@ -0,0 +1,58 @@
+% PUMA(1) PUMA user manuals
+% Bennett Piater and Justus Piater
+% January 07, 2017
+
+# NAME
+puma - simple password manager
+
+# SYNOPSIS
+puma [*options*] <account>
+
+# Description
+Log in automatically using the credentials for the specified account.
+
+This will type the user name, TAB, password and ENTER.
+
+# OPTIONS
+-h, \--help
+: Show a help message.
+
+-u
+: only type the user name and TAB
+
+-p
+: only type the password and ENTER
+
+# EXIT STATUS
+TODO
+
+# ENVIRONMENT
+PUMA_KEYRING
+: The folder containing the credential files. Defaults to *~/Documents/keyring*.
+
+# NOTES
+
+# BUGS
+
+# EXAMPLES
+To log into your google account, while having keyboard focus in the user name field:
+
+    puma google
+
+This assumes that $PUMA_KEYRING/google.gpg exists and is valid.
+
+# SEE ALSO
+**puma-add**(1), **puma**(7)
+
+# COPYRIGHT
+PUMA 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.
+PUMA 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 PUMA.  If not, see <http://www.gnu.org/licenses/>.

man7/puma.7.md

@@ -0,0 +1,57 @@
+% PUMA(7) PUMA user manuals
+% Bennett Piater and Justus Piater
+% January 07, 2017
+
+# NAME
+PUMA - simple password manager
+
+# PROGRAMS
+The following is just an overview, see the respective documentation for details.
+
+puma(1)
+: Log in using credentials.
+
+puma-add(1)
+: Helper script to simplify adding new credentials.
+
+puma-menu
+: Helper script providing interactive account selection for logging in using dmenu.
+
+# PURPOSE
+We wanted a very simple password manager, so we made this.
+All you need to use it is a folder with gpg-encrypted credential files.
+Subfolders aren't currently supported, but that won't be hard to add.
+
+To log in somewhere (as long as tab indices are properly set), simply invoke **puma** or **puma-menu** while having keyboard focus in the username field.
+
+I recommend binding **puma-menu** to some keyboard shortcut.
+
+# CREDENTIAL FILE SYNTAX
+Credential files are of the following form:
+
+    // ~/Documents/keyring/google.gpg
+    User: [email protected]
+    Pass: Tr0ub4dor&3
+
+Lines other than *User* and *Pass* are ignored and can be used for notes or any other information.
+
+# NOTES
+Some environment variables may need to be set. Check the documentation of the scripts before using them.
+
+# BUGS
+
+# SEE ALSO
+**puma**(1), **puma-add**(1)
+
+# COPYRIGHT
+PUMA 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.
+PUMA 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 PUMA.  If not, see <http://www.gnu.org/licenses/>.