classification
Title: Potentially hard to understand wording in devguide
Type: enhancement Stage: resolved
Components: Devguide Versions:
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: terry.reedy Nosy List: eric.araujo, ezio.melotti, python-dev, sandro.tosi, terry.reedy, tshepang
Priority: normal Keywords: patch

Created on 2012-01-11 10:41 by tshepang, last changed 2012-02-03 13:36 by eric.araujo. This issue is now closed.

Files
File name Uploaded Description Edit
rm-obsolete-reference.patch tshepang, 2012-01-11 10:41
rm-obsolete-reference2.patch tshepang, 2012-01-18 00:18
Messages (14)
msg151051 - (view) Author: Tshepang Lekhonkhobe (tshepang) * Date: 2012-01-11 10:41
this line:

"commonly abbreviated svn, after the program name"

was once changed to:

"commonly abbreviated hg, after the program name"

and it no longer makes sense
msg151095 - (view) Author: Sandro Tosi (sandro.tosi) * (Python committer) Date: 2012-01-11 22:12
But we may explain what's behind: "after the mercury chemical element symbol" - what do you think?
msg151096 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-01-11 22:19
If 'program' refers to the executable, the sentence is still valid.
msg151151 - (view) Author: Tshepang Lekhonkhobe (tshepang) * Date: 2012-01-12 21:36
On Thu, Jan 12, 2012 at 00:12, Sandro Tosi <report@bugs.python.org> wrote:
>
> Sandro Tosi <sandro.tosi@gmail.com> added the comment:
>
> But we may explain what's behind: "after the mercury chemical element symbol" - what do you think?

Good idea. That's actually what I thought it meant initially before
noticing it was (probably) left there accidentally.
msg151152 - (view) Author: Tshepang Lekhonkhobe (tshepang) * Date: 2012-01-12 21:46
> Ezio Melotti <ezio.melotti@gmail.com> added the comment:
>
> If 'program' refers to the executable, the sentence is still valid.

Interesting. It didn't appear like that until you mentioned it. It was
far more clear with subversion:svn than mercurial:hg. Sandro's
suggestion removes the ambiguity, although it would be kool to also
mention that it's also the program's name, since it seems to always be
used in that context.
msg151218 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-01-14 03:52
I understand the phrasing this way: The system is called Mercurial and commonly abbreviated “hg”, after the name of its main executable.  So we say “the hg server”, “I like the branches concept in hg”, etc.
msg151501 - (view) Author: Tshepang Lekhonkhobe (tshepang) * Date: 2012-01-18 00:18
I included both suggestions in the latest patch.
msg151502 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-01-18 00:30
I really think there is no bug.  We don’t have to explain why Mercurial or hg are named so.  The current text merely says that “hg”, which is the name of the executable, is commonly used as a short form of “Mercurial”.
msg151503 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-01-18 00:31
Adding a native speaker for confirmation.
msg151564 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2012-01-18 21:01
I read 'program name' as referring to 'Mercurial', not 'hg'. Perhaps Tshepang did also. Read that way, it is not right. Reading it the intended way is not so obvious to one who has never typed 'hg' on a command line. It would be impossible for one who does not even know that hg is the executable name.

Given that the intended audience is not limited to experienced hg users, I suggest changing "(commonly abbreviated hg, after the program name)" to the much clearer and explicit "The Mercurial executable is named 'hg', and 'hg' is often used to refer to Mercurial itself." (This is just a slight rewording of what Éric said is meant to be said.) 

I agree that we should not discuss the origin of 'hg'. The chemical symbol is 'Hg', whereas 'hg' (normally) abbreviates 'hectogram'. My suggestion simply states two facts that beginning cpython developers need to know.
msg151619 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-01-19 13:08
Thanks for commenting.  Please commit your wording, or this alternate version:

“``hg`` is the name of the Mercurial command-line program, and is often used as an abbreviation for "Mercurial".”

(Just to avoid repetition and to add “command-line”.)
msg151660 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2012-01-19 23:13
New changeset 081106c142ec by Terry Jan Reedy in branch 'default':
#13763 Clarify 'hg' usage.
http://hg.python.org/devguide/rev/081106c142ec
msg151661 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2012-01-19 23:19
I do not much like sentences starting with lowercase, so I combined our sentences. The result is good enough, I think. Closing.
msg152504 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-02-03 13:36
I like the result, thanks!
History
Date User Action Args
2012-02-03 13:36:40eric.araujosetmessages: + msg152504
2012-01-19 23:19:03terry.reedysetstatus: open -> closed
messages: + msg151661

assignee: terry.reedy
resolution: fixed
stage: patch review -> resolved
2012-01-19 23:13:47python-devsetnosy: + python-dev
messages: + msg151660
2012-01-19 13:08:36eric.araujosetmessages: + msg151619
2012-01-18 21:01:05terry.reedysetmessages: + msg151564
2012-01-18 00:31:33eric.araujosetnosy: + terry.reedy

messages: + msg151503
title: rm obsolete reference in devguide -> Potentially hard to understand wording in devguide
2012-01-18 00:30:32eric.araujosetmessages: + msg151502
2012-01-18 00:18:32tshepangsetfiles: + rm-obsolete-reference2.patch

messages: + msg151501
2012-01-14 03:52:51eric.araujosetnosy: + eric.araujo
messages: + msg151218
2012-01-12 21:46:40tshepangsetmessages: + msg151152
2012-01-12 21:36:49tshepangsetmessages: + msg151151
2012-01-11 22:19:57ezio.melottisettype: enhancement
messages: + msg151096
2012-01-11 22:12:37sandro.tosisetnosy: + sandro.tosi

messages: + msg151095
stage: patch review
2012-01-11 10:41:26tshepangcreate