Make description of presentation types f and e in format spec more clear

[Prometheus3375]

Some time ago I was reading docs of format specification mini-language and got a bit confused with the description for presentation type f. Because of my misunderstanding, I created #111125 thinking there is an error in docs. There I got an explanation what was actually meant.

Here is the current description of type f:

'f' -- Fixed-point notation. For a given precision p, formats the number as a decimal number with exactly p digits following the decimal point. With no precision given, uses a precision of 6 digits after the decimal point for float, and uses a precision large enough to show all coefficient digits for Decimal. If no digits follow the decimal point, the decimal point is also removed unless the # option is used.

The source of my confusion had come from the last sentence. I assumed that it refers to the case with no precision given mentioned in the previous sentence, but it actually refers to the case when p is zero. For comparison, the description of type g at first lists the case when no digits follow the decimal point, and then in a different paragraph lists the case with no precision given (I do not quote the description here because it is too large).

I suggest to rearrange two last sentences in descriptions of types f and e and maybe rephrase some parts. Here are two examples for type f.

Just rearrangement:

'f' -- Fixed-point notation. For a given precision p, formats the number as a decimal number with exactly p digits following the decimal point. If no digits follow the decimal point, the decimal point is also removed unless the # option is used. With no precision given, uses a precision of 6 digits after the decimal point for float, and uses a precision large enough to show all coefficient digits for Decimal.

Rearranged sentences with edited 2nd sentence.

'f' -- Fixed-point notation. For a given precision p, formats the number as a decimal number with exactly p digits following the decimal point. With a precision of 0, the decimal point is removed unless the # option is used. With no precision given, uses a precision of 6 digits after the decimal point for float, and uses a precision large enough to show all coefficient digits for Decimal.

Linked PRs

• gh-123133: clarify p=0 case for "f" and "e" formatting types #125426
• [3.13] gh-123133: clarify p=0 case for "f" and "e" formatting types (GH-125426) #125428
• [3.12] gh-123133: clarify p=0 case for "f" and "e" formatting types (GH-125426) #125429

[skirpichev]

The source of my confusion had come from the last sentence. I assumed that it refers to the case with no precision given mentioned in the previous sentence, but it actually refers to the case when p is zero.

I am not a native speaker of English, but for me it's pretty obvious from first two sentences, that "no digits follow the decimal point" case might correspond only to precision=0. "No precision given" means precision=6. Text seems very clear. Where is the source of confusion?

[Prometheus3375]

Where is the source of confusion?

I though that case "If no digits follow the decimal point" is a subcase for "With no precision given". For example, 1 or 1. have no digits after the decimal point, so I thought f'{1:f}' would result in '1' and f'{1:#f}' in '1.'.

[Prometheus3375]

The current description has the following structure: given precision -> no given precision -> specific given description. It would be more logical to not separate cases with given precision. I propose such structure: given precision -> specific given precision -> no given precision. Such structure is already present in the description of g type.

[skirpichev]

I though that case "If no digits follow the decimal point" is a subcase for "With no precision given".

You just ignored the first sentence. One told you that number of digits after the point is equal to precision.

The current description has the following structure: given precision -> no given precision -> specific given description.

Rather: full description of the precision setting (with defaults, 2nd sentence). Then specific behaviour for precision=0. I don't see what we gain, if discussion of defaults for precision will be the last sentence.

[skirpichev]

CC @picnixz

[picnixz]

I think I understand why there is a confusion. When we say "no digits follow the decimal point", we may think of "no digits follow the decimal point in the number being formatted" independently of the precision itself. For instance, you could expect f'{123:f}' to be 123 because 123 does not have a decimal point at all. Even if it's equivalent to f'{123:6f}', the fact is that there is no decimal point after 123.

While the meaning is clear and without ambiguities if you take your time to read the entire text, I agree that it might be confusing to some people, especially if this is something that beginners could stumble upon. What we can however say is:

"If p = 0 and no digits follow the decimal point, then [...], unless # [...]" but that's as far as I think we should change the docs. However, with the additional "unless" we have a bit of "if X and Y, we have [...], except if we don't have Z" which can also be even more confusing...

cc @willingc @ncoghlan as docs and formulation experts.

[skirpichev]

When we say "no digits follow the decimal point"

That's from the last sentence from the paragraph. It looks rather strange for me to interpret text from the end... But first two sentences clearly show 1) how many digits could be in the fractional part (exactly p) and thus 2) when there will be no digits (if p=0).

While the meaning is clear and without ambiguities if you take your time to read the entire text

I think there is no doubts, if you read 1) the whole text and 2) in the correct order.

But I would appreciate opinion of docs experts.

[willingc]

Thanks @picnixz for the summary and @skirpichev for asking for feedback from experts.

#111125 (comment) @serhiy-storchaka's example clarifies the behavior well, and it likely makes sense to add this for clarity. It could go in the "Example section" that follows the table.

Another alternative improvement would be to split the text into more than one paragraph.

Current text:

Fixed-point notation. For a given precision p, formats the number as a decimal number with exactly p digits following the decimal point. With no precision given, uses a precision of 6 digits after the decimal point for float, and uses a precision large enough to show all coefficient digits for Decimal. If no digits follow the decimal point, the decimal point is also removed unless the # option is used.

Modified text (changes in bold font):

Fixed-point notation. For a given precision p, formats the number as a decimal number with exactly p digits following the decimal point. When no precision given, uses a default precision of 6 digits after the decimal point for float, and uses a precision suitable to show all coefficient digits for Decimal.

If no digits follow the decimal point, the decimal point is also removed. The # option may be used to force display of the decimal point.

@Prometheus3375 Would this modified text clarify the behavior for you?

[serhiy-storchaka]

I suggest to write "If p=0, the decimal point is omitted unless the # option is used." or "If p=0, the decimal point is only added if the # option is used." or "The decimal point is omitted if p=0 and the # option is not used." Or something like.

[Prometheus3375]

@willingc the source of my confusion is phrase "If no digits follow the decimal point". Because what actually meant here is "If no digits follow the decimal point in the result of formatting", but I perceive this as "If no digits follow the decimal point in the number being formatted" or "If no digits follow the decimal point in the format string". I originally assumed the latter, but quick test had shown that this is an invalid format string, so I decided to try the former.

In this issue I referred to the description of g:

In both cases insignificant trailing zeros are removed from the significand, and the decimal point is also removed if there are no remaining digits following it, unless the '#' option is used.

Here it is clear that "if there are no remaining digits following it" refers to the moment after formatting is done by the provided context.

Re-evaluating my suggestions I provided in the issue, I think that replacement of "If no digits follow the decimal point" with "If p = 0" or "With a precision of 0" is enough; no rearrangement is needed. Though I would like to have a consistent usage of p and precision in the last two sentences, i.e., "With no precision given" and "With a precision of 0" or "If p is not given" and "If p = 0".

---

You just ignored the first sentence. One told you that number of digits after the point is equal to precision.

The sentence "For a given precision p, formats the number as a decimal number with exactly p digits following the decimal point" defines p as a number of digits in the result of formatting, but it does not specify that any further mention of "X digits follow the decimal point" is p. I do not perceive these phrases as interchangeable without additional context.

[skirpichev]

Ok, it seems OP is ok with Serhiy suggestion. I took liberty to make a small pr with this change: #125426

[willingc]

Closed by #125426. Thanks everyone for thoughtful discussion and a team effort to improve the description. ☀️