[New-bugs-announce] [issue26512] Vocabulary: Using "integral" in library/stdtypes.html

[Julien]

New submission from Julien:

o/

TL;DR: I think the various usages of "Integral" in https://docs.python.org/3.5/library/stdtypes.html#numeric-types-int-float-complex are either wrong or too hard to understand and should be rewriten as "int".


While translating the documentation I found the sentence "x truncated to Integral" in https://docs.python.org/3.5/library/stdtypes.html#numeric-types-int-float-complex for the `math.floor(x)` method.

By "Integral" I assume you're speaking about the ABC `numbers.Integral`, whish is already not clear, but the capital I helps.

According to pydoc and PEP3141, the `numbers.Integral` ABC inherits from Rational, which inherits from Real which inherits from Complex which inherits from Number. So number is the broader ABC and integral the opposite, the representation of an integer.

I do _NOT_ assume that someone reading the stdtypes.html section is aware of those ABCs, so I don't think it's nice for them to use them without linking to them.

So I infer than "x truncated to integral" means "x truncated to the nearest integer". Which is far more readable.

Two lines after, I found "The greatest integral float <= x" for `math.floor(x)` which is less readable, no capital I to `integral` and what is an `integral float` ?

Also the documentation of `math.floor` states an `int` is returned (as the doc for math.trunc states an Integral is returned).

So there's two possibilities here:

 - The doc uses vocabulary and phrase structures I don't understand and "integral float" actually mean something.
 - The doc is not clear

In both cases, I suggest to either transform "integral" usages to a link to :class:`numbers.Integral` or simply speaking of "int" here.

Context: I'm translating the documentation in French, I achieved `tutorial.html` and `functions.html` and it's until here the hardest sentence to understand (others were simply wrong like in http://bugs.python.org/issue26029) or understandable, so even if those structures are semantically and gramatically correct, they're clearly one of the hardest to understand, which is sad as we're only speaking of rounding numbers. I mean, if there's a goal to sand away spikes in doc readability, this one is a big one.

So, can an english native speaker can enlighten me about this ?

Bests,

----------
assignee: docs at python
components: Documentation
messages: 261380
nosy: docs at python, sizeof
priority: normal
severity: normal
status: open
title: Vocabulary: Using "integral" in library/stdtypes.html
type: enhancement
versions: Python 3.5

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue26512>
_______________________________________