diff --git a/README.md b/README.md
index adaa011..54e529d 100644
--- a/README.md
+++ b/README.md
@@ -147,13 +147,12 @@ The following adapters are disabled by default, and can be enabled using '--rga-
 
     Extensions: .jpg, .png
 
-update-readme.sh
+<!-- this part generated by update-readme.sh -->
+## USAGE:
 
-## USAGE
+> rga \[RGA OPTIONS\] \[RG OPTIONS\] PATTERN \[PATH \...\]
 
-> rga \[FLAGS\] \[OPTIONS\] PATTERN \[PATH ...\]
-
-## FLAGS
+## FLAGS:
 
 **\--rga-accurate**
 
@@ -179,13 +178,11 @@ update-readme.sh
 
 > Disable caching of results
 >
-> By default, rga caches the extracted text, if it is small enough,
-> to a database in `~/Library/Caches/rga` on macOS,
-> `~/.cache/rga` (on other Unixes),
-> or `C:\Users\username\AppData\Local\rga` (on Windows).
-> This way, repeated searches on
-> the same set of files will be much faster. If you pass this flag, all
-> caching will be disabled.
+> By default, rga caches the extracted text, if it is small enough, to a
+> database in \~/.cache/rga on Linux, *\~/Library/Caches/rga* on macOS,
+> or C:\\Users\\username\\AppData\\Local\\rga on Windows. This way,
+> repeated searches on the same set of files will be much faster. If you
+> pass this flag, all caching will be disabled.
 
 **\--rg-help**
 
@@ -211,15 +208,18 @@ update-readme.sh
 
 **\--rga-cache-compression-level=**\<cache-compression-level\>
 
-> \[default: 12\]
+> ZSTD compression level to apply to adapter outputs before storing in
+> cache db
+>
+> Ranges from 1 - 22 \[default: 12\]
 
-**\--rga-cache-max-blob-len**=\<cache-max-blob-len\>
+**\--rga-cache-max-blob-len=**\<cache-max-blob-len\>
 
 > Max compressed size to cache
 >
 > Longest byte length (after compression) to store in cache. Longer
-> adapter outputs will not be cached and recomputed every time.
-> \[default: 2000000\]
+> adapter outputs will not be cached and recomputed every time. Allowed
+> suffixes: k M G \[default: 2000000\]
 
 **\--rga-max-archive-recursion=**\<max-archive-recursion\>
 
@@ -230,10 +230,7 @@ advanced options.
 
 All other options not shown here are passed directly to rg, especially
 \[PATTERN\] and \[PATH \...\]
-
-[ripgrep]: https://github.com/BurntSushi/ripgrep
-
-update-readme.sh
+<!-- end of part generated by update-readme.sh -->
 
 ## Development
 
diff --git a/src/args.rs b/src/args.rs
index 271081c..a1807fd 100644
--- a/src/args.rs
+++ b/src/args.rs
@@ -61,7 +61,8 @@ set_default!(max_archive_recursion, 4, i32);
     about = env!("CARGO_PKG_DESCRIPTION"),
     author = env!("CARGO_PKG_HOMEPAGE"),
     // TODO: long_about does not seem to work to only show this on short help
-    after_help = "-h shows a concise overview, --help shows more detail and advanced options.\n\nAll other options not shown here are passed directly to rg, especially [PATTERN] and [PATH ...]"
+    after_help = "-h shows a concise overview, --help shows more detail and advanced options.\n\nAll other options not shown here are passed directly to rg, especially [PATTERN] and [PATH ...]",
+    usage = "rga [RGA OPTIONS] [RG OPTIONS] PATTERN [PATH ...]"
 )]
 pub struct RgaArgs {
     #[serde(default, skip_serializing_if = "is_default")]
@@ -69,9 +70,9 @@ pub struct RgaArgs {
     /// Disable caching of results
     ///
     /// By default, rga caches the extracted text, if it is small enough,
-    /// to a database in ~/Library/Caches/rga on macOS,
-    /// ~/.cache/rga on other Unixes,
-    /// or C:\Users\username\AppData\Local\rga` on Windows.
+    /// to a database in ~/.cache/rga on Linux,
+    /// ~/Library/Caches/rga on macOS,
+    /// or C:\Users\username\AppData\Local\rga on Windows.
     /// This way, repeated searches on the same set of files will be much faster.
     /// If you pass this flag, all caching will be disabled.
     pub no_cache: bool,
diff --git a/update-readme.sh b/update-readme.sh
new file mode 100755
index 0000000..e14f619
--- /dev/null
+++ b/update-readme.sh
@@ -0,0 +1,11 @@
+#!/bin/bash
+
+content=$(
+    cat <<END
+<!-- this part generated by update-readme.sh -->
+$(help2man -N "cargo run --bin rga --" | pandoc -f man -t markdown --atx-headers | rg --multiline "## USAGE:(.|\n)*")
+<!-- end of part generated by update-readme.sh -->
+END
+)
+
+rg --passthrough --multiline '.*update-readme.sh(.|\n)*update-readme.sh.*' README.md --replace "$content" | sponge README.md