On 8/12/2016 11:04 AM, Kain Abel wrote:
Dear developers, dear contributors, dear users,
I've found some gaps and inconsistencies in the documentation on command line.
Thank you for taking time to notice and point them out. The
documentation always benefits from critical readers since its authors
are also usually the developers and hence are often too close to the
trees to see the forest.
....
My starting point was: fossil init --help...
There is no hint for DATETIME in the 'See also:' section. (A good
format hint was found after a long time with "timeline --help".)
The (command line) documentation lacks the information of the format
and the supported subset of DATETIME or things like DATETIME can be a
string and must be surrounded by ''/"" or not.
Pretty much every command that takes a date and time has this
shortcoming in the documentation. I'll take a crack at improving that.
Until I get that done, the short answer is that it understands anything
that SQLite's strftime() understands as a "time string".
That means that many things that looks like a subset of an ISO8601 date
and time string will work. Either the date or time can be omitted (but
an omitted date will be 2001-01-01 which may not be obvious at a
glance), and a timezone may be added. The keyword "now" also works, as
does a fractional Julian day number.
See https://www.sqlite.org/lang_datefunc.html for the full story under
the heading "Time Strings". But note that as called from fossil, none of
the documented time modifiers are possible.
For fun, you can try feeding things to the test-date-format command:
$ fossil test-date-format now
now -> 2016-08-12T21:51:51.775
$ fossil test-date-format "2016-08-01 09:00:00-07:00" # PDT
2016-08-01 09:00:00-07:00 -> 2016-08-01T16:00:00.000
$ fossil test-date-format "2016-08-01 09:00:00Z" # Explicit UTC
2016-08-01 09:00:00Z -> 2016-08-01T09:00:00.000
Other to briefly documented formats are: TYPE and DATE.
It appears likely all references to a DATE are really a DATETIME. I'll
review that.
I'll fix up the date and time documentation, then consider the other
nits you've raised.
...
Supposed inconsistencies: (in the output of --help or a closer look at
'fossil test-all-help')
armend|branch|commit: the usage of DATE vs DATETIME?
the switch in armend: --date vs --date-override (used in init|commit|branch|tag)
Missing switch documentation -n for --dry-run in the help of command purge.
Missing switch documentation -v for --verbose in the help of command clone.
Missing (hidden) alias 'list' for command 'ls'. If 'ls' used as a
subcommand, then is always/mostly? the alias 'list' present.
(fossil list vs. fossil stash list)
Missing desciption of TYPE's in whatis.
Undocumented and missing type 'g' in timeline.
It is possible to introduce also unified shortcuts for the switches
--date-override|-OD (in branch, commit, tag)
--user-override|-OU (in branch, commit, tag, init|new)
?
They are long and ugly to type. ;)
I know I'm annoying:
Other wishes of commonly/often used switches (*x systems)
-h as shortcut for --help
-u as shortcut for --unified in diff
-b as shortcut for --brief in diff (was also used in dbstat, extras, finfo)
and also the silent switch -q as 2nd aka for compatibility with
GNU/diff --brief?
Thanks for your time and work!
Best regards,
Kain
_______________________________________________
fossil-users mailing list
fossil-users@lists.fossil-scm.org
http://lists.fossil-scm.org:8080/cgi-bin/mailman/listinfo/fossil-users
--
Ross Berteig r...@cheshireeng.com
Cheshire Engineering Corp. http://www.CheshireEng.com/
+1 626 303 1602
_______________________________________________
fossil-users mailing list
fossil-users@lists.fossil-scm.org
http://lists.fossil-scm.org:8080/cgi-bin/mailman/listinfo/fossil-users
