Move examples into manpage.

4 files changed, 224 insertions, 93 deletions

diff --git a/README b/README
index 8fb5d91..e07720c 100644
--- a/README
+++ b/README
@@ -8,99 +8,20 @@ This is a very simple password store that encrypts passwords using gpg and
 places the encrypted password in a directory. It can generate new passwords
 and keep track of old ones.
 
-If the password storage directory ($HOME/.password-store) is also a git
-repository, add/remove/change operations will create a corresponding git
-commit.
+Please see the man page for considerable more documentation and examples.
 
-Usage:
-    pass init gpg-id
-        Initialize new password storage and use gpg-id for encryption.
-    pass [ls] [subfolder]
-        List passwords.
-    pass [show] [--clip,-c] pass-name
-        Show existing password and optionally put it on the clipboard.
-        If put on the clipboard, it will be cleared in 45 seconds.
-    pass insert [--multiline,-m] pass-name
-        Insert new optionally multiline password.
-    pass generate [--no-symbols,-n] [--clip,-c] pass-name pass-length
-        Generate a new password of pass-length with optionally no symbols.
-        Optionally put it on the clipboard and clear board after 45 seconds.
-    pass rm pass-name
-        Remove existing password.
-    pass push
-        If the password store is a git repository, push the latest changes.
-    pass pull
-        If the password store is a git repository, pull the latest changes.
-    pass git git-command-args...
-        If the password store is a git repository, execute a git command
-	specified by git-command-args.
-    pass help
-        Show this text.
+You may read the man page without installing the package by one of these
+commands:
 
-See the man page for more options -- man 1 pass.
+- Show it in man:
 
+    $ man ./man/pass.1
 
-Examples:
+- Produce an HTML page:
 
-    - Initialize password store:
-    
-        zx2c4@laptop ~ $ pass init Jason@zx2c4.com
-        mkdir: created directory ‘/home/zx2c4/.password-store’
-        Password store initialized for Jason@zx2c4.com.
-    
-    - List existing passwords in store:
+    $ groff -mandoc -T html ./man/pass.1 > pass-man-page.html
 
-        zx2c4@laptop ~ $ pass
-        ├── Business
-        │   ├── some-silly-business-site.com
-        │   └── another-business-site.net
-        ├── Email
-        │   ├── donenfeld.com
-        │   └── zx2c4.com
-        └── France
-            ├── bank
-            ├── freebox
-            └── mobilephone
-        
-        Alternatively, "pass ls".
-
-    - Show existing password:
-
-        zx2c4@laptop ~ $ pass Email/zx2c4.com
-	sup3rh4x3rizmynam3
-    
-    - Add password to store:
-
-        zx2c4@laptop ~ $ pass insert Business/cheese-whiz-factory
-        Enter password for Business/cheese-whiz-factory: omg so much cheese what am i gonna do
-
-        Or, multiline passwords:
-
-        zx2c4@laptop ~ $ pass insert --multiline Business/cheese-whiz-factory
-        Enter contents of Business/cheese-whiz-factory and press Ctrl+D when finished:
-
-        Hey this is my 
-        awesome
-        multi
-        line
-        passworrrrrrrrd.
-        ^D
-
-    - Generate new password:
-
-        zx2c4@laptop ~ $ pass generate Email/jasondonenfeld.com 15
-        The generated password to Email/jasondonenfeld.com is:
-        $(-QF&Q=IN2nFBx
-
-        Or, with no symbols:
-
-        zx2c4@laptop ~ $ pass generate --no-symbols Email/jasondonenfeld.com 12
-        The generated password to Email/jasondonenfeld.com is:
-        YqFsMkBeO6di
-
-    - Remove password from store:
-
-        zx2c4@laptop ~ $ pass remove Business/cheese-whiz-factory
-        rm: remove regular file ‘/home/zx2c4/.password-store/Business/cheese-whiz-factory.gpg’? y
-        removed ‘/home/zx2c4/.password-store/Business/cheese-whiz-factory.gpg’
+- Produce a PDF document:
 
+    $ groff -mandoc ./man/pass.1 pass-man-page.ps
+    $ ps2pdf pass-man-page.ps
diff --git a/man/example-filter.sh b/man/example-filter.sh
new file mode 100755
index 0000000..2a71d40
--- /dev/null
+++ b/man/example-filter.sh
@@ -0,0 +1,22 @@
+#!/bin/sh
+
+# This is a super bootleg script for converting plaintext examples into groff.
+
+while read line; do
+	echo "$line" | while read -n 1 char; do
+		if [[ $char == "%" ]]; then
+			echo -n '%'
+			continue
+		fi
+		ord=$(printf '%d' "'$char")
+		if [[ $ord -eq 0 ]]; then
+			printf ' '
+		elif [[ $ord -gt 127 ]]; then
+			printf '\[u%X]' "'$char"
+		else
+			printf "$char"
+		fi
+	done
+	echo
+	echo ".br"
+done
diff --git a/man/pass.1 b/man/pass.1
index cfec222..b43ca8d 100644
--- a/man/pass.1
+++ b/man/pass.1
@@ -36,11 +36,17 @@ the valid commands listed below.
 Several of the commands below rely on or provide additional functionality if
 the password store directory is also a git repository. If the password store
 directory is a git repository, all password store modification commands will
-cause a corresponding git commit.
+cause a corresponding git commit. See the \fIEXAMPLES\fP section for an
+extended description using \fBinit\fP and
+.BR git (1).
 
 The \fBinit\fP command must be run before other commands in order to initialize
 the password store with the correct gpg key id.
 
+There is a corresponding bash completion script for use with tab completing
+password names in
+.BR bash (1).
+
 .SH COMMANDS
 
 .TP
@@ -100,13 +106,195 @@ using the password store as the git repository.
 \fBhelp\fP
 Show usage message.
 
+.SH EXAMPLES
+
+.TP
+Initialize password store
+.B zx2c4@laptop ~ $ pass init Jason@zx2c4.com 
+.br
+mkdir: created directory \[u2018]/home/zx2c4/.password-store\[u2019] 
+.br
+Password store initialized for Jason@zx2c4.com.
+.TP
+List existing passwords in store
+.B zx2c4@laptop ~ $ pass 
+.br
+Password Store
+.br
+\[u251C]\[u2500]\[u2500] Business 
+.br
+\[u2502]   \[u251C]\[u2500]\[u2500] some-silly-business-site.com 
+.br
+\[u2502]   \[u2514]\[u2500]\[u2500] another-business-site.net 
+.br
+\[u251C]\[u2500]\[u2500] Email 
+.br
+\[u2502]   \[u251C]\[u2500]\[u2500] donenfeld.com 
+.br
+\[u2502]   \[u2514]\[u2500]\[u2500] zx2c4.com 
+.br
+\[u2514]\[u2500]\[u2500] France 
+.br
+    \[u251C]\[u2500]\[u2500] bank 
+.br
+    \[u251C]\[u2500]\[u2500] freebox 
+.br
+    \[u2514]\[u2500]\[u2500] mobilephone  
+.br
+
+.br
+Alternatively, "\fBpass ls\fP".
+.TP
+Show existing password
+.B zx2c4@laptop ~ $ pass Email/zx2c4.com 
+.br
+sup3rh4x3rizmynam3 
+.TP
+Copy existing password to clipboard
+.B zx2c4@laptop ~ $ pass -c Email/zx2c4.com 
+.br
+Copied Email/jason@zx2c4.com to clipboard. Will clear in 45 seconds.
+.TP
+Add password to store
+.B zx2c4@laptop ~ $ pass insert Business/cheese-whiz-factory 
+.br
+Enter password for Business/cheese-whiz-factory: omg so much cheese what am i gonna do
+.TP
+Add multiline password to store 
+.B zx2c4@laptop ~ $ pass insert -m Business/cheese-whiz-factory 
+.br
+Enter contents of Business/cheese-whiz-factory and press Ctrl+D when finished: 
+.br
+ 
+.br
+Hey this is my 
+.br
+awesome 
+.br
+multi 
+.br
+line 
+.br
+passworrrrrrrrd. 
+.br
+^D 
+.TP
+Generate new password
+.B zx2c4@laptop ~ $ pass generate Email/jasondonenfeld.com 15 
+.br
+The generated password to Email/jasondonenfeld.com is: 
+.br
+$(-QF&Q=IN2nFBx
+.TP
+Generate new alphanumeric password
+.B zx2c4@laptop ~ $ pass -n generate Email/jasondonenfeld.com 12
+.br
+The generated password to Email/jasondonenfeld.com is: 
+.br
+YqFsMkBeO6di
+.TP
+Generate new password and copy it to the clipboard
+.B zx2c4@laptop ~ $ pass -c generate Email/jasondonenfeld.com 19
+.br
+Copied Email/jasondonenfeld.com to clipboard. Will clear in 45 seconds.
+.TP
+Remove password from store
+.B zx2c4@laptop ~ $ pass remove Business/cheese-whiz-factory 
+.br
+rm: remove regular file \[u2018]/home/zx2c4/.password-store/Business/cheese-whiz-factory.gpg\[u2019]? y 
+.br
+removed \[u2018]/home/zx2c4/.password-store/Business/cheese-whiz-factory.gpg\[u2019]
+.TP
+Initialize new password store, create a git repository, and then manipulate and sync passwords
+.B zx2c4@laptop ~ $ pass init Jason@zx2c4.com 
+.br
+mkdir: created directory \[u2018]/home/zx2c4/.password-store\[u2019] 
+.br
+Password store initialized for Jason@zx2c4.com. 
+.br
+.B zx2c4@laptop ~ $ pass git init 
+.br
+Initialized empty Git repository in /home/zx2c4/.password-store/.git/ 
+.br
+.B zx2c4@laptop ~ $ pass git remote add origin kexec.com:pass-store 
+.br
+.B zx2c4@laptop ~ $ pass generate Amazon/amazonemail@email.com 21 
+.br
+mkdir: created directory \[u2018]/home/zx2c4/.password-store/Amazon\[u2019] 
+.br
+[master (root-commit) 30fdc1e] Added generated password for Amazon/amazonemail@email.com to store. 
+.br
+1 file changed, 0 insertions(+), 0 deletions(-) 
+.br
+create mode 100644 Amazon/amazonemail@email.com.gpg 
+.br
+The generated password to Amazon/amazonemail@email.com is: 
+.br
+<5m,_BrZY`antNDxKN<0A 
+.br
+.B zx2c4@laptop ~ $ pass push -u --all 
+.br
+Counting objects: 4, done. 
+.br
+Delta compression using up to 2 threads. 
+.br
+Compressing objects: 100% (3/3), done. 
+.br
+Writing objects: 100% (4/4), 921 bytes, done. 
+.br
+Total 4 (delta 0), reused 0 (delta 0) 
+.br
+To kexec.com:pass-store 
+.br
+* [new branch]      master -> master 
+.br
+Branch master set up to track remote branch master from origin. 
+.br
+.B zx2c4@laptop ~ $ pass insert Amazon/otheraccount@email.com 
+.br
+Enter password for Amazon/otheraccount@email.com: som3r3a11yb1gp4ssw0rd!!88** 
+.br
+[master b9b6746] Added given password for Amazon/otheraccount@email.com to store. 
+.br
+1 file changed, 0 insertions(+), 0 deletions(-) 
+.br
+create mode 100644 Amazon/otheraccount@email.com.gpg 
+.br
+.B zx2c4@laptop ~ $ pass rm Amazon/amazonemail@email.com 
+.br
+rm: remove regular file \[u2018]/home/zx2c4/.password-store/Amazon/amazonemail@email.com.gpg\[u2019]? y 
+.br
+removed \[u2018]/home/zx2c4/.password-store/Amazon/amazonemail@email.com.gpg\[u2019] 
+.br
+rm 'Amazon/amazonemail@email.com.gpg' 
+.br
+[master 288b379] Removed Amazon/amazonemail@email.com from store. 
+.br
+1 file changed, 0 insertions(+), 0 deletions(-) 
+.br
+delete mode 100644 Amazon/amazonemail@email.com.gpg 
+.br
+.B zx2c4@laptop ~ $ pass push 
+.br
+Counting objects: 9, done. 
+.br
+Delta compression using up to 2 threads. 
+.br
+Compressing objects: 100% (5/5), done. 
+.br
+Writing objects: 100% (7/7), 1.25 KiB, done. 
+.br
+Total 7 (delta 0), reused 0 (delta 0) 
+.br
+To kexec.com:pass-store
+
 .SH FILES
 
 .TP
-\fB~/.password-store\fP
+.B ~/.password-store
 The password storage directory.
 .TP
-\fB~/.password-store/.gpg-id\fP
+.B ~/.password-store/.gpg-id
 Contains the gpg key identification used for encryption and decryption. This should
 be set using the \fBinit\fP command.
 
diff --git a/src/password-store.sh b/src/password-store.sh
index 2c6bd12..d9c139b 100755
--- a/src/password-store.sh
+++ b/src/password-store.sh
@@ -227,7 +227,7 @@ case "$command" in
 		fi
 		;;
 	git)
-		if [[ -d $GIT ]]; then
+		if [[ $1 == "init" ]] || [[ -d $GIT ]]; then
 			exec git $@
 		else
 			echo "Error: the password store is not a git repository."