Re: documentation update for doc/src/sgml/func.sgml

Hi,

attached is a small patch which updates doc/src/sgml/func.sgml. The
change explains that functions like round() and others might behave
different depending on your operating system (because of rint(3)) and
that this is according to an IEEE standard. It also points out that #.5
is not always rounded up, as expected from a mathematical point of view.

Regards,

--
Andreas 'ads' Scherbaum
German PostgreSQL User Group
European PostgreSQL User Group - Board of Directors
Volunteer Regional Contact, Germany - PostgreSQL Project

> attached is a small patch which updates doc/src/sgml/func.sgml. The change
> explains that functions like round() and others might behave different
> depending on your operating system (because of rint(3)) and that this is
> according to an IEEE standard. It also points out that #.5 is not always
> rounded up, as expected from a mathematical point of view.

Applied on head & read. I'm not a native English speaker, but the English
looked right to me.

Comments:

I'm not sure that the "note that" on the third line is useful.

I do not understand why the last sentence in the first paragraph about
bitwise ops is put there with rounding issues, which seem unrelated. It
seems to me that it belongs to the second paragraph which is about bitwise
operators.

The wikipedia link can be simplified to a much cleaner:

http://en.wikipedia.org/wiki/IEEE_floating_point#Rounding_rules

Also, I submitted docs with relevant wikipedia links which was stripped of
these before committing. I'm wondering whether there is a general policy
not to put external links from within the text in the documentation. There
are very few of them, most in "acronym.sgml".

I would suggest to put relevant tags around functions and types, like:
"<function>round()</>" and "<type>NUMERIC</>".

--
Fabien.

On 08/21/2014 11:53 AM, Fabien COELHO wrote:
>
>> attached is a small patch which updates doc/src/sgml/func.sgml. The
>> change explains that functions like round() and others might behave
>> different depending on your operating system (because of rint(3)) and
>> that this is according to an IEEE standard. It also points out that
>> #.5 is not always rounded up, as expected from a mathematical point of
>> view.
>
> Applied on head & read. I'm not a native English speaker, but the
> English looked right to me.

Thanks.

> Comments:
>
> I'm not sure that the "note that" on the third line is useful.
>
> I do not understand why the last sentence in the first paragraph about
> bitwise ops is put there with rounding issues, which seem unrelated. It
> seems to me that it belongs to the second paragraph which is about
> bitwise operators.

That's the part which came from Josh Berkus. We discussed this patch on IRC.

> The wikipedia link can be simplified to a much cleaner:
>
> http://en.wikipedia.org/wiki/IEEE_floating_point#Rounding_rules

It can, but then you always refer to the latest version of the Wikipedia
page, which might or might not be a good idea. The link in the patch
points to the current version from yesterday, no matter how many changes
are introduced afterwards.

But yes:

> Also, I submitted docs with relevant wikipedia links which was stripped
> of these before committing. I'm wondering whether there is a general
> policy not to put external links from within the text in the
> documentation. There are very few of them, most in "acronym.sgml".

It would be nice to have a general rule how to handle external links.

> I would suggest to put relevant tags around functions and types, like:
> "<function>round()</>" and "<type>NUMERIC</>".

Can do.

Thanks,

--
Andreas 'ads' Scherbaum
German PostgreSQL User Group
European PostgreSQL User Group - Board of Directors
Volunteer Regional Contact, Germany - PostgreSQL Project

>> I do not understand why the last sentence in the first paragraph about
>> bitwise ops is put there with rounding issues, which seem unrelated. It
>> seems to me that it belongs to the second paragraph which is about
>> bitwise operators.
>
> That's the part which came from Josh Berkus. We discussed this patch on IRC.

Hmmm. I do think the last sentence belongs to the next paragraph. The
identity of the author does not change my opinion on that point:-) If you
have another argument, maybe.

>> The wikipedia link can be simplified to a much cleaner:
>>
>> http://en.wikipedia.org/wiki/IEEE_floating_point#Rounding_rules
>
> It can, but then you always refer to the latest version of the Wikipedia
> page, which might or might not be a good idea. The link in the patch points
> to the current version from yesterday, no matter how many changes are
> introduced afterwards.

I doubt that IEEE floating point rounding rules are likely to change much,
so referencing the latest version is both safe & cleaner. Also, wikipedia
would change its implementation from php to something else (well,
unlikely, probably as unlikely as a change in IEEE fp rounding rules:-).

--
Fabien.

On 08/21/2014 12:35 PM, Fabien COELHO wrote:
>
>
>>> I do not understand why the last sentence in the first paragraph
>>> about bitwise ops is put there with rounding issues, which seem
>>> unrelated. It seems to me that it belongs to the second paragraph
>>> which is about bitwise operators.
>>
>> That's the part which came from Josh Berkus. We discussed this patch
>> on IRC.
>
> Hmmm. I do think the last sentence belongs to the next paragraph. The
> identity of the author does not change my opinion on that point:-) If
> you have another argument, maybe.

Attached is an updated version of the patch.

>>> The wikipedia link can be simplified to a much cleaner:
>>>
>>> http://en.wikipedia.org/wiki/IEEE_floating_point#Rounding_rules
>>
>> It can, but then you always refer to the latest version of the
>> Wikipedia page, which might or might not be a good idea. The link in
>> the patch points to the current version from yesterday, no matter how
>> many changes are introduced afterwards.
>
> I doubt that IEEE floating point rounding rules are likely to change
> much, so referencing the latest version is both safe & cleaner. Also,
> wikipedia would change its implementation from php to something else
> (well, unlikely, probably as unlikely as a change in IEEE fp rounding
> rules:-).

It's really not about the IEEE changing something, but about someone
changing the Wikipedia page. The way I linked it makes sure it always
displays the same version of the page.

Of course a general rule how to link to WP would be nice ...

Regards,

--
Andreas 'ads' Scherbaum
German PostgreSQL User Group
European PostgreSQL User Group - Board of Directors
Volunteer Regional Contact, Germany - PostgreSQL Project

> Attached is an updated version of the patch.

Ok.

I notice that you decided against adding tags around function and type
names.

> It's really not about the IEEE changing something, but about someone
> changing the Wikipedia page. The way I linked it makes sure it always
> displays the same version of the page.

I understood that. I think that the likelyhood of someone removing the
section about rounding in the IEEE standard is very low, and the current
php link is pretty ugly from a REST perspective, and would prevent to see
the possible improved version of the page. Well, no big deal.

> Of course a general rule how to link to WP would be nice ...

I'm afraid that the current implicit rule is more or less "no links", at
least there are very few of them but in the glossary, and when I submitted
docs with them they were removed before committing.

However I do support the idea that these links are useful references and
should be put where appropriate, even if it means that there must be some
updates from time to time.

--
Fabien.

Fabien COELHO-3 wrote
>> Of course a general rule how to link to WP would be nice ...
>
> I'm afraid that the current implicit rule is more or less "no links", at
> least there are very few of them but in the glossary, and when I submitted
> docs with them they were removed before committing.

Ideally if external links were to be allowed PostgreSQL.org would maintain a
URL shortening service and those shortened links would be in the
documentation so that any necessary pointers could be changed immediately
and without source updates.

David J.

--
View this message in context: http://postgresql.1045698.n5.nabble.com/documentation-update-for-doc-src-sgml-func-sgml-tp5815621p5818924.html
Sent from the PostgreSQL - hackers mailing list archive at Nabble.com.

>>> Of course a general rule how to link to WP would be nice ...
>>
>> I'm afraid that the current implicit rule is more or less "no links", at
>> least there are very few of them but in the glossary, and when I submitted
>> docs with them they were removed before committing.
>
> Ideally if external links were to be allowed PostgreSQL.org would maintain a
> URL shortening service and those shortened links would be in the
> documentation so that any necessary pointers could be changed immediately
> and without source updates.

Why not. This would mean maintaining the redirection table somewhere. That
would also be a place to check whether some links become dandling
pointers. However there are also implications on the infrastructure to
host these redirections. Maybe one page on wiki.postgresql.org could be
used for this purpose.

--
Fabien.

On 9/12/14 3:13 PM, Andreas 'ads' Scherbaum wrote:
> Of course a general rule how to link to WP would be nice ...

I think Wikipedia links should be avoided altogether. We can assume
that readers are technically proficient to look up general technical
concepts on their own using a reference system of their choice.

In cases where a link is warranted, it is better to construct a proper
bibliographic citation to the primary source material, such as an IEEE
standard or an academic paper, in a way that will stand the test of time.

Another problem, which the bibliography system partially addresses, is
that if we patch things like proposed here, we'll end up with
inconsistent linking all over the documentation wherever the concept is
mentioned. For example, we already make reference to the relevant IEEE
standard where floating-point types are first introduced in section
8.1.3, and we probably don't need to repeat "floating-point numbers are
weird" every time they are mentioned later on.

Independent of that, it is actually not correct that "we use the IEEE's
rules", because "we" don't use any rules, that is up to the operating
system/platform. While most platforms indeed do use the IEEE
floating-point standard more less, some don't. Section 8.1.3 tries to
point that out.

On 09/14/2014 06:32 PM, Peter Eisentraut wrote:
> On 9/12/14 3:13 PM, Andreas 'ads' Scherbaum wrote:
>> Of course a general rule how to link to WP would be nice ...
>
> I think Wikipedia links should be avoided altogether. We can assume
> that readers are technically proficient to look up general technical
> concepts on their own using a reference system of their choice.
>
> In cases where a link is warranted, it is better to construct a proper
> bibliographic citation to the primary source material, such as an IEEE
> standard or an academic paper, in a way that will stand the test of time.

That's a clear statement, and makes sense. Should be written down
somewhere, so it can be found again.

> Independent of that, it is actually not correct that "we use the IEEE's
> rules", because "we" don't use any rules, that is up to the operating
> system/platform. While most platforms indeed do use the IEEE
> floating-point standard more less, some don't. Section 8.1.3 tries to
> point that out.

New version attached, WP link removed, wording changed.

Regards,

--
Andreas 'ads' Scherbaum
German PostgreSQL User Group
European PostgreSQL User Group - Board of Directors
Volunteer Regional Contact, Germany - PostgreSQL Project

On Sat, Oct 18, 2014 at 4:12 AM, Andreas 'ads' Scherbaum
<adsmail(at)wars-nicht(dot)de> wrote:
> On 09/14/2014 06:32 PM, Peter Eisentraut wrote:
>>
>> On 9/12/14 3:13 PM, Andreas 'ads' Scherbaum wrote:
>>>
>>> Of course a general rule how to link to WP would be nice ...
>>
>>
>> I think Wikipedia links should be avoided altogether. We can assume
>> that readers are technically proficient to look up general technical
>> concepts on their own using a reference system of their choice.
>>
>> In cases where a link is warranted, it is better to construct a proper
>> bibliographic citation to the primary source material, such as an IEEE
>> standard or an academic paper, in a way that will stand the test of time.
>
>
> That's a clear statement, and makes sense. Should be written down somewhere,
> so it can be found again.
>
>
>> Independent of that, it is actually not correct that "we use the IEEE's
>> rules", because "we" don't use any rules, that is up to the operating
>> system/platform. While most platforms indeed do use the IEEE
>> floating-point standard more less, some don't. Section 8.1.3 tries to
>> point that out.
>
>
> New version attached, WP link removed, wording changed.
Documentation format is still incorrect. The function names should be
put in a block <function>, same for the value 0.5 with <literal> and
the data types NUMERIC and REAL. Corrected patch is attached. The rest
looks fine to me, I am switching it to Ready for committer.
--
Michael

Here is a slight update so that type names are treated homogeneously
between both added paragraphs.

ITSM that this patch should be committed without further ado.

--
Fabien.

On Wed, Dec 31, 2014 at 9:44 AM, Fabien COELHO <coelho(at)cri(dot)ensmp(dot)fr> wrote:
> Here is a slight update so that type names are treated homogeneously between
> both added paragraphs.
>
> ITSM that this patch should be committed without further ado.

I had a look at this patch. This patch adds some text below a table
of functions. Immediately above that table, there is this existing
language:

The functions working with <type>double precision</type> data are mostly
implemented on top of the host system's C library; accuracy and behavior in
boundary cases can therefore vary depending on the host system.

This seems to me to substantially duplicate the information added by the patch.

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

> I had a look at this patch. This patch adds some text below a table
> of functions. Immediately above that table, there is this existing
> language:
>
> The functions working with <type>double precision</type> data are mostly
> implemented on top of the host system's C library; accuracy and behavior in
> boundary cases can therefore vary depending on the host system.
>
> This seems to me to substantially duplicate the information added by the patch.

I would rather say that it explicites the potential issues. Taking that
into account, maybe the part about floating point could be moved up after
the above sentence, or the above sentence moved down as an introduction,
with some pruning so that it fits in?

The second paragraph about bitwise ops is not related to these.

--
Fabien.

On Tue, Jan 20, 2015 at 4:01 AM, Fabien COELHO <coelho(at)cri(dot)ensmp(dot)fr> wrote:
>> I had a look at this patch. This patch adds some text below a table
>> of functions. Immediately above that table, there is this existing
>> language:
>>
>> The functions working with <type>double precision</type> data are mostly
>> implemented on top of the host system's C library; accuracy and behavior
>> in
>> boundary cases can therefore vary depending on the host system.
>>
>> This seems to me to substantially duplicate the information added by the
>> patch.
>
> I would rather say that it explicites the potential issues. Taking that into
> account, maybe the part about floating point could be moved up after the
> above sentence, or the above sentence moved down as an introduction, with
> some pruning so that it fits in?

Possibly. If anyone still cares about this patch, then they should
try revising it along those lines and submit an updated version. If
no one is excited enough about this to do that, we should just flag
this as rejected and move on. Since this patch has been kicking
around since August, my reading is nobody's very excited about it, but
maybe I'm misinterpreting the situation.

> The second paragraph about bitwise ops is not related to these.

Yeah, I'm not quite sure how that got in here; I don't see discussion
of it upthread. It looks like it ought to be a completely separate
patch with its own discussion, FWICS.

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

On Mon, Feb 2, 2015 at 10:42 PM, Robert Haas <robertmhaas(at)gmail(dot)com> wrote:

> On Tue, Jan 20, 2015 at 4:01 AM, Fabien COELHO <coelho(at)cri(dot)ensmp(dot)fr>
> wrote:
> >> I had a look at this patch. This patch adds some text below a table
> >> of functions. Immediately above that table, there is this existing
> >> language:
> >>
> >> The functions working with <type>double precision</type> data are
> mostly
> >> implemented on top of the host system's C library; accuracy and
> behavior
> >> in
> >> boundary cases can therefore vary depending on the host system.
> >>
> >> This seems to me to substantially duplicate the information added by the
> >> patch.
> >
> > I would rather say that it explicites the potential issues. Taking that
> into
> > account, maybe the part about floating point could be moved up after the
> > above sentence, or the above sentence moved down as an introduction, with
> > some pruning so that it fits in?
>
> Possibly. If anyone still cares about this patch, then they should
> try revising it along those lines and submit an updated version. If
> no one is excited enough about this to do that, we should just flag
> this as rejected and move on. Since this patch has been kicking
> around since August, my reading is nobody's very excited about it, but
> maybe I'm misinterpreting the situation.

Let's move on then, marked as rejected.
--
Michael