Hyphenation suggestions - floating-point/floating point

[joenapnap]

BPO	14164
Nosy	@merwok, @akheron
Files	patch.diff: fixes some hyphens

^{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 = None
closed_at = <Date 2012-03-01.18:20:29.825>
created_at = <Date 2012-03-01.12:25:25.159>
labels = ['type-feature', 'docs']
title = 'Hyphenation suggestions - floating-point/floating point'
updated_at = <Date 2012-03-02.05:06:05.206>
user = 'https://bugs.python.org/joenapnap'

bugs.python.org fields:

activity = <Date 2012-03-02.05:06:05.206>
actor = 'eric.araujo'
assignee = 'docs@python'
closed = True
closed_date = <Date 2012-03-01.18:20:29.825>
closer = 'brian.curtin'
components = ['Documentation']
creation = <Date 2012-03-01.12:25:25.159>
creator = 'joenapnap'
dependencies = []
files = ['24695']
hgrepos = []
issue_num = 14164
keywords = ['patch']
message_count = 8.0
messages = ['154688', '154691', '154694', '154696', '154708', '154709', '154710', '154729']
nosy_count = 8.0
nosy_names = ['eric.araujo', 'eli.bendersky', 'docs@python', 'petri.lehtinen', 'poq', 'joenapnap', 'Matthew.Johnson', 'Andrew.Smith']
pr_nums = []
priority = 'normal'
resolution = 'rejected'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue14164'
versions = ['Python 2.7', 'Python 3.2', 'Python 3.3']

[joenapnap]

This patch fixes some small grammar things in the docs. Hope you like my contribution.

[akheron]

See also bpo-13868 by Retro.

[elibendersky]

John, thanks for the contribution, however this is not a valid fix.

See the Wikipedia page for floating point: http://en.wikipedia.org/wiki/Floating_point

No dash!

There is no need to go over the Python docs fixing such "mistakes". If you have time to contribute to Python, there's *plenty* of opportunities to do so in a useful way.

[MatthewJohnson]

I think he's right to fix those "mistakes". Just see the first sentence @ http://docs.python.org/tutorial/floatingpoint.html#floating-point-arithmetic-issues-and-limitations

It reads: "Floating-point numbers are represented in [...]"

So as you can see, there are places in the docs where the hyphen/dash is there, other places where it is not. I, personally, don't get the whole "some places yes, someplaces no" philosophy. I think the patch should be applied. I think he was just trying to make some consistentcy in the docs as his first contribution.

I must also point out that I don't understand the whole "some places title-case, other places sentence-case" titles in the docs. It's kind of confusing.

What are your thoughts about all this?

[poq]

It is generally considered more correct to write "floating-point number", because "floating-point" is a compound adjective here. The hyphen clarifies that it should be parsed as ((floating point) number) instead of (floating (point number)).

However, in practice "floating point number" is also commonly used. I completely agree with Eli that this is just nitpicking, and not a productive use of Python developers' time.

[briancurtin]

Hyphenation changes are not going to be made unless the current text is actually incorrect, confusing, or leads to people misunderstanding what is meant.

[AndrewSmith]

I think he was trying to say that there is inconsistency in the docs... And since you guys are all about consistency... Why the punch below the belt?

[merwok]

Python has a lot of known and unknown bugs that need to be fixed, many missing features needing to be implemented, and a lot of room for improvement in its documentation. That’s why we welcome people who want to help.

You’re not the first one to propose a trivial typographic patch that is rejected. I’m writing this long-ish message to serve as a reference for future rejections.

Maybe you thought it would be a risk-free way to become a contributor, but as it turns out, this kind of patches is not helpful. All Python developers are volunteers, and we review bugs and patches on our limited free time. It is worthwhile to fix clear errors, ambiguities, outdated facts and wrong advice in the documentation; it is not worthwhile to add or remove a few commas and hyphens just for consistency’s sake. (Moreover, hyphens in English don’t have rules as clear as we commonly think, like poq pointed.)

There is no “some places title-case, other places sentence-case” philosophy; different people wrote various parts of the documentation, and we just live with it. We fix bugs, improve code, add examples, think about missing features, read specifications, reply to email, improve wordings; we just don’t have the time to care about questionable changes that don’t add any value for us or our users. Consistency is a design principle; it does not mean obsessive polishing. There are also other principles that are equally valid, and also pure pragmatic constraints.

John and Matthew, you are more than welcome to report bugs you find, or to work on fixing a bug, from the long list of bugs that really would improve people’s life when fixed. If you are unsure about the process or about your patch, please join http://mail.python.org/mailman/listinfo/core-mentorship mailing list to ask any question you might have: we will help you.

Hope this clarifies things without hurting anyone’s feelings.