Re: [HACKERS] documentation update for doc/src/sgml/func.sgml
On Mon, Feb 2, 2015 at 10:42 PM, Robert Haas robertmh...@gmail.com wrote: On Tue, Jan 20, 2015 at 4:01 AM, Fabien COELHO coe...@cri.ensmp.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 typedouble 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
Re: [HACKERS] documentation update for doc/src/sgml/func.sgml
On Tue, Jan 20, 2015 at 4:01 AM, Fabien COELHO coe...@cri.ensmp.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 typedouble 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 -- Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-hackers
Re: [HACKERS] documentation update for doc/src/sgml/func.sgml
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 typedouble 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. -- Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-hackers
Re: [HACKERS] documentation update for doc/src/sgml/func.sgml
On Wed, Dec 31, 2014 at 9:44 AM, Fabien COELHO coe...@cri.ensmp.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 typedouble 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 -- Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-hackers
Re: [HACKERS] documentation update for doc/src/sgml/func.sgml
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.diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index 2016c5a..f91033b 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -939,6 +939,26 @@ /tgroup /table + para +For functions like functionround()/, functionlog()/ and +functionsqrt()/ which run against either fixed-precision +(typenumeric/) or floating-point numbers (e.g. typereal/), +note that the results of these operations will differ according +to the input type due to rounding. This is most observable with +functionround()/, which can end up rounding down as well as up for +any literal0.5/ value. productnamePostgreSQL/productname's +handling of floating-point values depends on the operating system, which +may or may not follow the IEEE floating-point standard. + /para + + para +The bitwise operators work only on integral data types, whereas +the others are available for all numeric data types. The bitwise +operators are also available for the bit string types +typebit/ and typebit varying/, as +shown in xref linkend=functions-bit-string-op-table. + /para + para xref linkend=functions-math-random-table shows functions for generating random numbers. -- Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-hackers
Re: [HACKERS] documentation update for doc/src/sgml/func.sgml
On Sat, Oct 18, 2014 at 4:12 AM, Andreas 'ads' Scherbaum adsm...@wars-nicht.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 diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index 6f30946..f6b865e 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -939,6 +939,26 @@ /tgroup /table + para +For functions like functionround()/, functionlog()/ and +functionsqrt()/ which run against either fixed-precision +(literalNUMERIC/) or floating-point numbers (e.g. literalREAL/), +note that the results of these operations will differ according +to the input type due to rounding. This is most observable with +functionround()/, which can end up rounding down as well as up for +any literal0.5/ value. productnamePostgreSQL/productname's +handling of floating-point values depends on the operating system, which +may or may not follow the IEEE floating-point standard. + /para + + para +The bitwise operators work only on integral data types, whereas +the others are available for all numeric data types. The bitwise +operators are also available for the bit string types +typebit/type and typebit varying/type, as +shown in xref linkend=functions-bit-string-op-table. + /para + para xref linkend=functions-math-random-table shows functions for generating random numbers. -- Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-hackers
Re: [HACKERS] documentation update for doc/src/sgml/func.sgml
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 diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index 13c71af..d54cf58 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -924,6 +924,25 @@ /tgroup /table + para +For functions like round(), log() and sqrt() which run against +either fixed-precision (NUMERIC) or floating-point numbers (e.g. REAL), +note that the results of these operations will differ according +to the input type due to rounding. This is most observable with +round(), which can end up rounding down as well as up for +any #.5 value. productnamePostgreSQL/productname's handling +of floating-point values depends on the operating system, which +may or may not follow the IEEE floating-point standard. + /para + + para +The bitwise operators work only on integral data types, whereas +the others are available for all numeric data types. The bitwise +operators are also available for the bit string types +typebit/type and typebit varying/type, as +shown in xref linkend=functions-bit-string-op-table. + /para + para xref linkend=functions-math-random-table shows functions for generating random numbers. -- Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-hackers
Re: [HACKERS] documentation update for doc/src/sgml/func.sgml
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. -- Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-hackers
Re: [HACKERS] documentation update for doc/src/sgml/func.sgml
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. -- Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-hackers
Re: [HACKERS] documentation update for doc/src/sgml/func.sgml
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. -- Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-hackers
Re: [HACKERS] documentation update for doc/src/sgml/func.sgml
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. -- Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-hackers
Re: [HACKERS] documentation update for doc/src/sgml/func.sgml
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 diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index 13c71af..15742f8 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -924,6 +924,25 @@ /tgroup /table + para +For functions like round(), log() and sqrt() which run against +either fixed-precision (NUMERIC) or floating-point numbers (e.g. REAL), +note that the results of these operations will differ according +to the input type due to rounding. This is most observable with +round(), which can end up rounding down as well as up for +any #.5 value. We use the +a xmlns=http://en.wikipedia.org/w/index.php?title=IEEE_floating_pointoldid=622007055#Rounding_rules;IEEE's rules/a +for rounding floating-point numbers which can be machine-specific. + /para + + para +The bitwise operators work only on integral data types, whereas +the others are available for all numeric data types. The bitwise +operators are also available for the bit string types +typebit/type and typebit varying/type, as +shown in xref linkend=functions-bit-string-op-table. + /para + para xref linkend=functions-math-random-table shows functions for generating random numbers. -- Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-hackers
Re: [HACKERS] documentation update for doc/src/sgml/func.sgml
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: functionround()/ and typeNUMERIC/. -- Fabien. -- Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-hackers
Re: [HACKERS] documentation update for doc/src/sgml/func.sgml
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: functionround()/ and typeNUMERIC/. Can do. Thanks, -- Andreas 'ads' Scherbaum German PostgreSQL User Group European PostgreSQL User Group - Board of Directors Volunteer Regional Contact, Germany - PostgreSQL Project -- Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-hackers
Re: [HACKERS] documentation update for doc/src/sgml/func.sgml
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. -- Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-hackers
