*: Refer to `zodb help tidrange` about how history range should be specified

- add help tidrange topic.
- change all commands to refer to it.
- add TODO to parse tid from absolute and relative dates (e.g.
  1.month.ago, similarly to how git can do). Dateparser

	https://dateparser.readthedocs.io/

  will probably be of help here.

/reviewed-on nexedi/zodbtools!7

zodbtools/help.py

+# -*- coding: utf-8 -*-
 # zodbtools - help topics
-# Copyright (C) 2017  Nexedi SA and Contributors.
-#                     Kirill Smelkov <kirr@nexedi.com>
+# Copyright (C) 2017-2018  Nexedi SA and Contributors.
+#                          Kirill Smelkov <kirr@nexedi.com>
 #
 # This program is free software: you can Use, Study, Modify and Redistribute
 # it under the terms of the GNU General Public License version 3, or (at your
@@ -51,4 +52,37 @@ Please see zodburi documentation for full details:
 http://docs.pylonsproject.org/projects/zodburi/
 """
 
-topic_dict['zurl'] = "specifying database URL", help_zurl
+help_tidrange = """\
+Many zodb commands can be invoked on specific range of database history and
+accept <tidrange> parameter for that. The syntax for <tidrange> is
+
+    tidmin..tidmax
+
+where tidmin and tidmax specify [tidmin, tidmax] range of transactions, ends
+inclusive. Both tidmin and tidmax are optional and default to
+
+    tidmin: 0   (start of database history)
+    tidmax: +∞  (end of database history)
+
+If a tid (tidmin or tidmax) is given, it has to be specified as follows:
+
+    - a 16-digit hex number specifying transaction ID, e.g. 0285cbac258bf266
+
+    TODO (recheck what git does and use dateparser):
+
+    - absolute timestamp,
+    - relative timestamp, e.g. yesterday, 1.week.ago
+
+Example tid ranges:
+
+    ..                                  whole database history
+    000000000000aaaa..                  transactions starting from 000000000000aaaa till latest
+    ..000000000000bbbb                  transactions starting from database beginning till 000000000000bbbb
+    000000000000aaaa..000000000000bbbb  transactions starting from 000000000000aaaa till 000000000000bbbb
+
+In commands <tidrange> is optional - if it is not given at all, it defaults to
+0..+∞, i.e. to whole database history.
+"""
+
+topic_dict['zurl']      = "specifying database URL",    help_zurl
+topic_dict['tidrange']  = "specifying history range",   help_tidrange

zodbtools/util.py

@@ -64,6 +64,9 @@ def txnobjv(txn):
 class TidRangeInvalid(Exception):
     pass
 
+# parse_tidrange parses a string into (tidmin, tidmax).
+#
+# see `zodb help tidrange` for accepted tidrange syntax.
 def parse_tidrange(tidrange):
     try:
         tidmin, tidmax = tidrange.split("..")

zodbtools/zodbanalyze.py

@@ -243,9 +243,10 @@ def analyze_rec(report, record):
 
 __doc__ = """%(program)s: Analyzer for ZODB data or repozo deltafs
 
-usage: %(program)s [options] <storage> [tidmin..tidmax]
+usage: %(program)s [options] <storage> [<tidrange>]
 
 <storage> is an URL (see 'zodb help zurl') or /path/to/file.deltafs(*)
+<tidrange> is a history range (see 'zodb help tidrange') to analyze.
 
 Options:
   -h, --help                 this help screen

zodbtools/zodbcmp.py

 # -*- coding: utf-8 -*-
-# Copyright (C) 2016-2017  Nexedi SA and Contributors.
+# Copyright (C) 2016-2018  Nexedi SA and Contributors.
 #                          Kirill Smelkov <kirr@nexedi.com>
 #
 # This program is free software: you can Use, Study, Modify and Redistribute
@@ -20,7 +20,7 @@
 """Zodbcmp - Tool to compare two ZODB databases
 
 Zodbcmp compares two ZODB databases in between tidmin..tidmax transaction range
-with default range being -∞..+∞ - (whole database).
+with default range being 0..+∞ - (whole database).
 
 For comparison both databases are scanned at storage layer and every
 transaction content is compared bit-to-bit between the two. The program stops
@@ -121,6 +121,7 @@ Usage: zodb cmp [OPTIONS] <storage1> <storage2> [tidmin..tidmax]
 Compare two ZODB databases.
 
 <storageX> is an URL (see 'zodb help zurl') of a ZODB-storage.
+<tidrange> is a history range (see 'zodb help tidrange') to compare.
 
 Options:
 

zodbtools/zodbdump.py

@@ -229,10 +229,11 @@ summary = "dump content of a ZODB database"
 
 def usage(out):
     print("""\
-Usage: zodb dump [OPTIONS] <storage> [tidmin..tidmax]
+Usage: zodb dump [OPTIONS] <storage> [<tidrange>]
 Dump content of a ZODB database.
 
 <storage> is an URL (see 'zodb help zurl') of a ZODB-storage.
+<tidrange> is a history range (see 'zodb help tidrange') to dump.
 
 Options: