# HG changeset patch
# User Andreas Nolda <andreas@nolda.org>
# Date 1699097326 -3600
#      Sat Nov 04 12:28:46 2023 +0100
# Node ID cf8df0aa233c772dcfcfbbd44c2a3a20decf2399
# Parent  cca280ec68d18441639791d0118c3f47a1496cce
subdivide README.md

diff --git a/README.md b/README.md
--- a/README.md
+++ b/README.md
@@ -7,6 +7,10 @@
 The script is released 'as is' with no warranty under the
 [GNU General Public License, version 2.0](https://hg.sr.ht/~nolda/xgrep/browse/COPYING).
 
+
+Requirements
+------------
+
 It requires the following Python 3 packages:
 
 * [blessings](https://pypi.org/project/blessings/)
@@ -16,29 +20,40 @@
 
     sudo apt-get install python3-blessings python3-lxml
 
-Usage:
+Usage
+-----
+
+The script is to be used as follows:
+
+    usage: xgrep.py [-h] [-a] [-c] [-C] [-i] [-l] [-L] [-m] [-M]
+                    [-n] [-N] [-p] [-P] [-q] [-r ns] [-s] [-v]
+                    expr file [file ...]
+
+    positional arguments:
+      expr                  XPath 1.0 expression
+      file                  XML file
 
-    xgrep.py [-a] [--abbreviate]
-             [-c] [--count]
-             [-C] [--force-color]
-             [-i] [--indent]
-             [-l] [--files-with-matches]
-             [-L] [--files-without-match]
-             [-m] [--matches]
-             [-M] [--files-and-matches]
-             [-n] [--line-number]
-             [-N] [--declare-ns]
-             [-p] [--pis]
-             [-P] [--comments]
-             [-q] [--quiet]
-             [-r <ns>] [--regex <ns>]
-             [-s] [--spaces]
-             <XPath expression>
-             <XML file(s)>
-
-    xgrep.py [-v] [--version]
-
-    xgrep.py [-h] [--help]
+    optional arguments:
+      -h, --help            show this help message and exit
+      -a, --abbreviate      abbreviate matches
+      -c, --count           count matches
+      -C, --force-color     preserve color and formatting when piping output
+      -i, --indent          indent matches
+      -l, --files-with-matches
+                            output list of matching files
+      -L, --files-without-match
+                            output list of non-matching files
+      -m, --matches         output list of matches
+      -M, --files-and-matches
+                            output list of files and matches
+      -n, --line-number     output line number of match start
+      -N, --declare-ns      declare namespaces in matches
+      -p, --pis             preserve processing-instructions in output
+      -P, --comments        preserve comments in output
+      -q, --quiet           only return exit status
+      -r ns, --regex ns     namespace prefix for EXSLT regular expressions
+      -s, --spaces          normalize whitespace to spaces
+      -v, --version         show program's version number and exit
 
 Normally, `xgrep.py` outputs the matching parts of the XML files together with
 their file names and the XPath expression. The option `-m` outputs only the