From 3c9d398484fb6e188e665be8299d6e5e89924c94 Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Fri, 23 Dec 2016 12:53:09 -0500
Subject: [PATCH] Doc: improve index entry for "median".
We had an index entry for "median" attached to the percentile_cont function
entry, which was pretty useless because a person following the link would
never realize that that function was the one they were being hinted to use.
Instead, make the index entry point at the example in syntax-aggregates,
and add a <seealso> link to "percentile".
Also, since that example explicitly claims to be calculating the median,
make it use percentile_cont not percentile_disc. This makes no difference
in terms of the larger goals of that section, but so far as I can find,
nearly everyone thinks that "median" means the continuous not discrete
calculation.
Per gripe from Steven Winfield. Back-patch to 9.4 where we introduced
percentile_cont.
Discussion: https://postgr.es/m/20161223102056.25614.1166@wrigleys.postgresql.org
---
doc/src/sgml/func.sgml | 3 ---
doc/src/sgml/syntax.sgml | 14 ++++++++++++--
2 files changed, 12 insertions(+), 5 deletions(-)
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 0f9c9bf129..10e31868ba 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -13774,9 +13774,6 @@ SELECT xmlagg(x) FROM (SELECT x FROM test ORDER BY y DESC) AS tab;
<primary>percentile</primary>
<secondary>continuous</secondary>
</indexterm>
- <indexterm>
- <primary>median</primary>
- </indexterm>
<function>percentile_cont(<replaceable class="parameter">fraction</replaceable>) WITHIN GROUP (ORDER BY <replaceable class="parameter">sort_expression</replaceable>)</function>
</entry>
<entry>
diff --git a/doc/src/sgml/syntax.sgml b/doc/src/sgml/syntax.sgml
index 000da39250..4ea667bd52 100644
--- a/doc/src/sgml/syntax.sgml
+++ b/doc/src/sgml/syntax.sgml
@@ -1694,11 +1694,21 @@ SELECT string_agg(a ORDER BY a, ',') FROM table; -- incorrect
case, write just <literal>()</> not <literal>(*)</>.
(<productname>PostgreSQL</> will actually accept either spelling, but
only the first way conforms to the SQL standard.)
+ </para>
+
+ <para>
+ <indexterm>
+ <primary>median</primary>
+ </indexterm>
+ <indexterm>
+ <primary>median</primary>
+ <seealso>percentile</seealso>
+ </indexterm>
An example of an ordered-set aggregate call is:
<programlisting>
-SELECT percentile_disc(0.5) WITHIN GROUP (ORDER BY income) FROM households;
- percentile_disc
+SELECT percentile_cont(0.5) WITHIN GROUP (ORDER BY income) FROM households;
+ percentile_cont
-----------------
50489
</programlisting>