[docs] TZ offset description is unclear in docs (issue 8810)

ben+python at benfinney.id.au ben+python at benfinney.id.au
Mon Sep 10 03:24:15 CEST 2012


Thank you very much for reviewing this patch.


http://bugs.python.org/review/8810/diff/5785/Doc/library/datetime.rst
File Doc/library/datetime.rst (right):

http://bugs.python.org/review/8810/diff/5785/Doc/library/datetime.rst#newcode1011
Doc/library/datetime.rst:1011: west from UTC.
On 2012/09/09 19:52:19, sasha wrote:

> The sentence above still uses slightly incorrect terminology. UTC is
> timescale and not a geographical location. There is no such point or a
line
> on our planet called UTC, so it is not correct to speak about things
east or
> west of UTC.

You're right that UTC is not a geographical location. It is a region in
the
abstract one-dimensional circular space of time zones, and other time
zones are
east or west from that region in the space of time zones.

Because those time zones map continuously (though not monotonically) to
geographical regions, it is correct and useful to use “east” and “west”
to
describe the relative positions of time zones in the space of time
zones,
because those two directions map in both spaces the same way.

> If you read UTC here as the Greenwich meridian, then the sentence is
> incorrect because there are places west of Greenwich that use negative
> offsets.

Don't do that, then :-) UTC is not the same as the Greenwich meridian,
and this
passage doesn't imply that anywhere, so reading them as identical will
lead to
incorrect conclusions.

http://bugs.python.org/review/8810/diff/5785/Doc/library/datetime.rst#newcode1049
Doc/library/datetime.rst:1049: Note that the name is 100% informational
– there's no requirement that it
On 2012/09/09 19:52:19, sasha wrote:
> 100% is redundant here.  I would just say "is informational."

It's not quite redundant; it carries the implication that there is no
purpose
*other than* the informational. I think that's the main point of this
sentence
(which I didn't write, merely moved).

Would you prefer “is only informational”? I think that would be better.

http://bugs.python.org/review/8810/diff/5785/Doc/library/datetime.rst#newcode1050
Doc/library/datetime.rst:1050: mean anything in particular. For example,
``"GMT"``, ``"UTC"``, ``"-500"``,
On 2012/09/09 19:52:19, sasha wrote:
> Grammar?  "it mean" -> "it means" or "for it to mean"

The sentence is correct English grammar, AFAICT; it refers to the
action, not the state. “there is no requirement that it mean foo” has
the same meaning as “there is no requirement for it to mean foo”, but
the former is less clumsy IMO.

http://bugs.python.org/review/8810/diff/5785/Doc/library/datetime.rst#newcode1931
Doc/library/datetime.rst:1931: 
On 2012/09/09 19:52:19, sasha wrote:
> Spurious empty line?

Checking the source in my tree, yes, it's spurious. That blank line can
be deleted without a problem.

http://bugs.python.org/review/8810/


More information about the docs mailing list