kpcyrd · kpcyrd · Jun 16, 2022 · Jun 16, 2022 · Jun 16, 2022
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -0,0 +1,18 @@
+name: Docs
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Install dependencies
+      run: sudo apt-get install scdoc
+    - name: Build
+      run: make docs
diff --git a/.gitignore b/.gitignore
@@ -1,2 +1,2 @@
 /target
-**/*.rs.bk
+contrib/*.1
diff --git a/Makefile b/Makefile
@@ -0,0 +1,4 @@
+docs: contrib/progpick.1
+
+contrib/%.1: contrib/%.1.scd
+	scdoc < $^ > $@
diff --git a/contrib/progpick.1.scd b/contrib/progpick.1.scd
@@ -0,0 +1,77 @@
+progpick(1)
+
+# NAME
+
+progpick - Bruteforce with a stream of permutations of a specific pattern
+
+# SYNOPSIS
+
+*progpick* [-vqc] [-e _cmd_] _PATTERN_
+
+# DESCRIPTION
+
+*progpick* is a program to generate permutations of an explicitly provided
+pattern. It's useful if you forgot some details about a passphrase but you
+still remember most of it.
+
+# OPTIONS
+
+*-v*, *--verbose*
+	Verbose logs (can be used multiple times, maximum: 4)
+
+*-q*, *--quiet*
+	Do not print progress bar
+
+*-c*, *--count*
+	Count total number of permutations instead of printing them
+
+*-e* _cmd_, *--exec* _cmd_
+	Send permutations to stdin of a subprocess. _cmd_ is parsed into a list of
+	arguments and then executed directly instead of going through /bin/sh, so
+	shell quoting works, but other shell features don't.
+
+*-h*, *--help*
+	Prints help information.
+
+# EXAMPLES
+
+Generate all combinations from a-z with a length of 5
+
+	*progpick '{a..z}{a..z}{a..z}{a..z}{a..z}'*
+
+With progress bar
+
+	*progpick '{a..z}{a..z}{a..z}{a..z}{a..z}' > /dev/null*
+
+Without progress bar
+
+	*progpick -q '{a..z}{a..z}{a..z}{a..z}{a..z}' > /dev/null*
+
+To make a character optional
+
+	*progpick '{a..z}{{a..z},}'*
+
+From a-z and 0-9
+
+	*progpick '{{a..z},{0..9}}'*
+
+Run a script for each result
+
+	*progpick 'a{b,c{d,e{f,g}}}' | while read -r x; do*
+		*./script "$x"*
+	*done*
+
+Send the result to stdin of a script
+
+	*progpick -e './script.sh' 'a{b,c{d,e{f,g}}}'*
+
+Attempt to open a luks partition
+
+	*sudo progpick -e 'cryptsetup open --test-passphrase /dev/sdc1' 'a{b,c{d,e{f,g}}}'*
+
+# AUTHORS
+
+This program was originally written and is currently maintained by kpcyrd.
+Bug reports and patches are welcome on github:
+
+	_https://github.com/kpcyrd/progpick_
diff --git a/src/main.rs b/src/main.rs
@@ -13,16 +13,16 @@ mod tokens;
 
 #[derive(Debug, Parser)]
 pub struct Args {
-    /// Verbose logs (can be used multiple times)
+    /// Verbose logs (can be used multiple times, maximum: 4)
     #[clap(short, long, parse(from_occurrences))]
     verbose: u8,
-    /// Count options instead of printing them
+    /// Count total number of permutations instead of printing them
     #[clap(short = 'c', long = "count")]
     count: bool,
     /// Do not print progress bar
     #[clap(short = 'q', long = "quiet")]
     quiet: bool,
-    /// Send permutations to a subprocess (arguments are supported but shell syntax is not)
+    /// Send permutations to stdin of a subprocess
     #[clap(short = 'e', long = "exec")]
     exec: Option<String>,
     pattern: Pattern,