Potentially hard to understand wording in devguide

[tshepang]

BPO	13763
Nosy	@terryjreedy, @ezio-melotti, @merwok, @sandrotosi
Files	rm-obsolete-reference.patch rm-obsolete-reference2.patch

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = 'https://github.com/terryjreedy'
closed_at = <Date 2012-01-19.23:19:03.833>
created_at = <Date 2012-01-11.10:41:26.791>
labels = ['type-feature', 'docs']
title = 'Potentially hard to understand wording in devguide'
updated_at = <Date 2012-02-03.13:36:40.790>
user = 'https://bugs.python.org/tshepang'

bugs.python.org fields:

activity = <Date 2012-02-03.13:36:40.790>
actor = 'eric.araujo'
assignee = 'terry.reedy'
closed = True
closed_date = <Date 2012-01-19.23:19:03.833>
closer = 'terry.reedy'
components = ['Devguide']
creation = <Date 2012-01-11.10:41:26.791>
creator = 'tshepang'
dependencies = []
files = ['24200', '24269']
hgrepos = []
issue_num = 13763
keywords = ['patch']
message_count = 14.0
messages = ['151051', '151095', '151096', '151151', '151152', '151218', '151501', '151502', '151503', '151564', '151619', '151660', '151661', '152504']
nosy_count = 6.0
nosy_names = ['terry.reedy', 'ezio.melotti', 'eric.araujo', 'sandro.tosi', 'tshepang', 'python-dev']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue13763'
versions = []

[tshepang]

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

[sandrotosi]

But we may explain what's behind: "after the mercury chemical element symbol" - what do you think?

[ezio-melotti]

If 'program' refers to the executable, the sentence is still valid.

[tshepang]

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.

[tshepang]

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.

[merwok]

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.

[tshepang]

I included both suggestions in the latest patch.

[merwok]

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”.

[merwok]

Adding a native speaker for confirmation.

[terryjreedy]

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.

[merwok]

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”.)

[python-dev]

New changeset 081106c142ec by Terry Jan Reedy in branch 'default':
bpo-13763 Clarify 'hg' usage.
http://hg.python.org/devguide/rev/081106c142ec

[terryjreedy]

I do not much like sentences starting with lowercase, so I combined our sentences. The result is good enough, I think. Closing.

[merwok]

I like the result, thanks!