Re: [PATCH v3 5/6] date: document and test "raw-local" mode

[Jeff King <peff@peff.net>]

On Wed, Jul 27, 2016 at 12:49:40PM -0700, Junio C Hamano wrote:

> > @@ -746,7 +746,10 @@ format, often found in email messages.
> >  +
> >  `--date=short` shows only the date, but not the time, in `YYYY-MM-DD` format.
> >  +
> > -`--date=raw` shows the date in the internal raw Git format `%s %z` format.
> > +`--date=raw` shows the date in the internal raw Git format `%s %z`
> > +format. Note that the `-local` option does not affect the
> > +seconds-since-epoch value (which is always measured in UTC), but does
> > +switch the accompanying timezone value.
> 
> Not your fault, but "internal raw Git format X format" sounds a bit
> clunky.

Yeah, I also noticed that while writing the original, but it just
crossed over my line of "if I fix everything I don't like, this series
will never get out the door". :)

> 	shows the date in `%s %z` format (seconds since 1970-01-01
> 	00:00:00 UTC, space, timezone as sign and four digits)
>         
> or something like that?  I suspect %s is not a POSIX-kosher strftime
> conversion specifier, so from that point of view, perhaps making the
> text the authoritative description and demote the format string as a
> comment to help those who know strfmt, i.e.
> 
> 	shows the date as seconds since 1970-01-01 00:00:00 UTC,
> 	space, timezone as sign and four digits (i.e. as if the
> 	timestamp were formatted with `strftime("%s %z")`).

Yeah, I think referring to "%s %z" is pretty bad, as it's meaningless to
people who don't know strftime() off the top of their head, and %s isn't
even portable.

The second option you've shown here is much better, and I think this is
worth fixing (and it should be in a new patch, and can go on top of the
others).

I'm not sure if it's worth calling out more clearly what the timezone
means, since the epoch seconds are in UTC, as you noted here. The
follow-on sentence explains what "-local" does, but not what it means in
the non-local variant.

-Peff