tools/qvm-firewall: improve manpage and --help output

doc/manpages/qvm-firewall.rst

@@ -31,11 +31,11 @@ Options
 
 .. option:: --reload, -r
 
-   force reloading rules even when unchanged
+   force reload of rules even when unchanged
 
 .. option:: --raw
 
-   Print raw rules when listing
+   in combination with :option:`--list`, print raw rules
 
 
 Actions description
@@ -45,7 +45,8 @@ Available actions:
 
 * add - add specified rule. See `Rule syntax` section below.
 
-* del - delete specified rule. Can be selected either by rule number using :option:`--rule-no`, or specifying rule itself.
+* del - delete specified rule. The rule to remove can be selected either by rule number using :option:`--rule-no`
+  or by specifying the rule itself using the same syntax used for adding it.
 
 * list - list all the rules for a given VM.
 
@@ -59,8 +60,8 @@ A single rule is built from:
  - action - either ``drop`` or ``accept``
  - zero or more matches
 
-Selected action is applied on given packet when all specified matches do match,
-further rules are not evaluated. If none of the rules match, default action
+Selected action is applied to packets when all specified matches match,
+further rules are not evaluated. If none of the rules match, the default action
 (``policy``) is applied.
 
 Supported matches:
@@ -76,9 +77,9 @@ Supported matches:
  - ``proto`` - specific IP protocol. Supported values: ``tcp``, ``udp``,
    ``icmp``.
 
- - ``dstports`` - destination port or ports range. Can be either a single port,
+ - ``dstports`` - destination port or ports range. Can be either a single port
    or a range separated by ``-``. Valid only together with ``proto=udp`` or
- ``proto=tcp``.
+   ``proto=tcp``.
 
  - ``icmptype`` - ICMP message type, specified as numeric value. Valid only
    together with ``proto=icmp``.
@@ -86,9 +87,10 @@ Supported matches:
  - ``specialtarget`` - predefined target. Currently the only supported value is
    ``dns``. This can be combined with other matches to narrow it down.
 
- - ``expire`` - rule matches only until specified time and then is automatically
- removed. The time can be given either as number of seconds since 1/1/1970, or
- ``+seconds`` as a relative time (``+300`` means 5 minutes from now).
+ - ``expire`` - the rule matches only until the specified time and is then
+   automatically removed. The time can be given either as number of seconds
+   since 1/1/1970 or as ``+seconds``, a relative time (``+300`` means 5
+   minutes from now).
 
 Authors
 -------

qubesadmin/tools/qvm_firewall.py

@@ -87,7 +87,7 @@ And as keyword arguments:
 Both formats, positional and keyword arguments, can be used
 interchangeably.
 
-Available rules:
+Available matches:
     action:        accept or drop
     dst4           synonym for dsthost
     dst6           synonym for dsthost
@@ -101,9 +101,9 @@ Available rules:
     specialtarget  only the value dns is currently supported,
                      it matches the configured dns servers of
                      a VM
-    expire         a rule is automatically removed at given time, given as
-                     seconds since 1/1/1970, or +seconds (e.g. +300 for rule
-                     expire in 5 minutes)
+    expire         the rule is automatically removed at the time given as
+                     seconds since 1/1/1970, or +seconds (e.g. +300 for a rule
+                     to expire in 5 minutes)
 """
 
 parser = qubesadmin.tools.QubesArgumentParser(vmname_nargs=1, epilog=epilog,
@@ -113,20 +113,20 @@ action = parser.add_subparsers(dest='command', help='action to perform')
 
 action_add = action.add_parser('add', help='add rule')
 action_add.add_argument('--before', type=int, default=None,
-    help='Add rule before rule with given number, instead of at the end')
-action_add.add_argument('rule', nargs='+', action=RuleAction,
+    help='Add rule before rule with given number instead at the end')
+action_add.add_argument('rule', metavar='match', nargs='+', action=RuleAction,
     help='rule description')
 
 action_del = action.add_parser('del', help='remove rule')
 action_del.add_argument('--rule-no', dest='rule_no', type=int,
     action='store', help='rule number')
-action_del.add_argument('rule', nargs='*', action=RuleAction,
+action_del.add_argument('rule', metavar='match', nargs='*', action=RuleAction,
     help='rule to be removed')
 
 action_list = action.add_parser('list', help='list rules')
 
 parser.add_argument('--reload', '-r', action='store_true',
-    help='force reloading rules even when unchanged')
+    help='force reload of rules even when unchanged')
 
 parser.add_argument('--raw', action='store_true',
     help='output rules as raw strings, instead of nice table')