Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Hyphenation suggestions - floating-point/floating point #58372

Closed
joenapnap mannequin opened this issue Mar 1, 2012 · 8 comments
Closed

Hyphenation suggestions - floating-point/floating point #58372

joenapnap mannequin opened this issue Mar 1, 2012 · 8 comments
Labels
docs Documentation in the Doc dir type-feature A feature request or enhancement

Comments

@joenapnap
Copy link
Mannequin

joenapnap mannequin commented Mar 1, 2012

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
    Copy link
    Mannequin Author

    joenapnap mannequin commented Mar 1, 2012

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

    @joenapnap joenapnap mannequin assigned docspython Mar 1, 2012
    @joenapnap joenapnap mannequin added docs Documentation in the Doc dir type-feature A feature request or enhancement labels Mar 1, 2012
    @akheron
    Copy link
    Member

    akheron commented Mar 1, 2012

    See also bpo-13868 by Retro.

    @elibendersky
    Copy link
    Mannequin

    elibendersky mannequin commented Mar 1, 2012

    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
    Copy link
    Mannequin

    MatthewJohnson mannequin commented Mar 1, 2012

    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
    Copy link
    Mannequin

    poq mannequin commented Mar 1, 2012

    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
    Copy link
    Member

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

    @briancurtin briancurtin changed the title my little contribution to the docs Hyphenation suggestions - floating-point/floating point Mar 1, 2012
    @AndrewSmith
    Copy link
    Mannequin

    AndrewSmith mannequin commented Mar 1, 2012

    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
    Copy link
    Member

    merwok commented Mar 2, 2012

    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.

    @ezio-melotti ezio-melotti transferred this issue from another repository Apr 10, 2022
    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
    Labels
    docs Documentation in the Doc dir type-feature A feature request or enhancement
    Projects
    None yet
    Development

    No branches or pull requests

    3 participants