main: Improve help message

Group message matching into two main parts (context and timestamps) and
simplify the help text for each option. Rename 'query' to 'keyword' to
avoid confusion with SQL queries and IRC queries.

Additionally, change some option flags to better communicate the type of
option (upper-case ones are used less frequently) or to make sure no
future option clashes with a less-frequently used one.

1 files changed, 21 insertions, 19 deletions

diff --git a/quarg/main.py b/quarg/main.py
index c9a3557..083166c 100644
--- a/quarg/main.py
+++ b/quarg/main.py
@@ -15,24 +15,26 @@ from quarg.utils import errx
 
 # pylint: disable=line-too-long
 cli = argparse.ArgumentParser()
-cli.add_argument('query', nargs='*', help='match messages containing this query')
-cli.add_argument('-d', action='store_true', dest='debug', help='print SQL query information')
-cli.add_argument('-e', action='store_true', dest='expr', help='interpret query as LIKE expression')
-cli.add_argument('-b', action='append', dest='buffer', help='match messages sent to this buffer')
-cli.add_argument('-B', action=actions.ParseBufferType, dest='buftype', help='match messages sent to buffers of this type')
-cli.add_argument('-n', action='append', dest='nick', help='match messages sent by this nickname')
-cli.add_argument('-N', action='append', dest='network', help='match messages sent to this network')
-cli.add_argument('-u', action='append', dest='user', help='match messages sent to this quassel user')
-cli.add_argument('-t', action=actions.ParseMessageType, dest='msgtype', help='match messages of this message type')
-cli.add_argument('-f', action=actions.ParseMessageFlag, dest='msgflag', help='match messages with this flag')
-cli.add_argument('-m', action='append', dest='umode', help='match messages sent by users with this mode')
-cli.add_argument('--after', action=actions.ParseDate, metavar='DATE', help='match messages sent after this date')
-cli.add_argument('--before', action=actions.ParseDate, metavar='DATE', help='match messages sent before this date')
-cli.add_argument('--around', action=actions.ParseAround, metavar='DATE', help='match messages sent within 12 hours of this date')
-
-joined_group = cli.add_mutually_exclusive_group()
-joined_group.add_argument('--joined', default=None, action='store_true', dest='joined', help='match messages sent to channels which are currently joined')
-joined_group.add_argument('--no-joined', default=None, action='store_false', dest='joined', help='match messages sent to channels which are not currently joined')
+cli.add_argument('keyword', nargs='*', help='match messages containing this keyword')
+cli.add_argument('-d', action='store_true', dest='debug', help='print debug and SQL query information')
+cli.add_argument('-e', action='store_true', dest='expr', help='interpret keywords as LIKE expression')
+matchers = cli.add_argument_group('matching message context')
+matchers.add_argument('-b', action='append', dest='buffer', help='match this buffer')
+matchers.add_argument('-B', action=actions.ParseBufferType, dest='buftype', help='match buffers of this type')
+matchers.add_argument('-n', action='append', dest='nick', help='match this nickname')
+matchers.add_argument('-m', action='append', dest='umode', help='match nicknames with this mode')
+matchers.add_argument('-N', action='append', dest='network', help='match this network')
+matchers.add_argument('-Q', action='append', dest='user', help='match this quassel user')
+matchers.add_argument('-t', action=actions.ParseMessageType, dest='msgtype', help='match this message type')
+matchers.add_argument('-f', action=actions.ParseMessageFlag, dest='msgflag', help='match this message flag')
+date_matchers = cli.add_argument_group('matching message timestamps')
+date_matchers.add_argument('--after', action=actions.ParseDate, metavar='DATE', help='sent after this date')
+date_matchers.add_argument('--before', action=actions.ParseDate, metavar='DATE', help='sent before this date')
+date_matchers.add_argument('--around', action=actions.ParseAround, metavar='DATE[/RANGE]', help='sent RANGE hours before or after this date')
+
+joined_group = matchers.add_mutually_exclusive_group()
+joined_group.add_argument('--joined', default=None, action='store_true', dest='joined', help='match buffers which are currently joined')
+joined_group.add_argument('--no-joined', default=None, action='store_false', dest='joined', help='match buffers which are not currently joined')
 # pylint: enable=line-too-long
 
 Session = sessionmaker()
@@ -56,7 +58,7 @@ def check_args(args):
 
 def collect_predicates(args):
     funs = {
-        'query':   filters.msg_like if args.expr else filters.msg_contains,
+        'keyword':   filters.msg_like if args.expr else filters.msg_contains,
         'buffer':  filters.buffer,
         'nick':    filters.nick,
         'after':   filters.time_after,