Thread: 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
Attachment
> 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
Attachment
> 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
Attachment
On Sat, Oct 18, 2014 at 4:12 AM, Andreas 'ads' Scherbaum <adsmail@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
Attachment
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@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 <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@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 <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
<div dir="ltr"><br /><div class="gmail_extra"><br /><div class="gmail_quote">On Mon, Feb 2, 2015 at 10:42 PM, Robert Haas<span dir="ltr"><<a href="mailto:robertmhaas@gmail.com" target="_blank">robertmhaas@gmail.com</a>></span> wrote:<br/><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div class="HOEnZb"><divclass="h5">On Tue, Jan 20, 2015 at 4:01 AM, Fabien COELHO <<a href="mailto:coelho@cri.ensmp.fr">coelho@cri.ensmp.fr</a>>wrote:<br /> >> I had a look at this patch. This patchadds some text below a table<br /> >> of functions. Immediately above that table, there is this existing<br />>> language:<br /> >><br /> >> The functions working with <type>double precision</type>data are mostly<br /> >> implemented on top of the host system's C library; accuracy and behavior<br/> >> in<br /> >> boundary cases can therefore vary depending on the host system.<br /> >><br/> >> This seems to me to substantially duplicate the information added by the<br /> >> patch.<br/> ><br /> > I would rather say that it explicites the potential issues. Taking that into<br /> > account,maybe the part about floating point could be moved up after the<br /> > above sentence, or the above sentencemoved down as an introduction, with<br /> > some pruning so that it fits in?<br /><br /></div></div>Possibly. If anyone still cares about this patch, then they should<br /> try revising it along those linesand submit an updated version. If<br /> no one is excited enough about this to do that, we should just flag<br /> thisas rejected and move on. Since this patch has been kicking<br /> around since August, my reading is nobody's very excitedabout it, but<br /> maybe I'm misinterpreting the situation.</blockquote></div><br /></div><div class="gmail_extra">Let'smove on then, marked as rejected.<br />-- <br /><div class="gmail_signature">Michael<br /></div></div></div>