Re: Inconsistent index links

Hi all,

I noticed that all aggregate functions listed in the documentation
index direct to a page listing all the aggregate functions and their
usage, with the exception of count, max, min and sum, which direct to
the aggregate function tutorial page. From the index, these sections
are indistinguishable from one another since they share the same page
name. I'm wondering if one should be named differently, like
Aggregate Functions Tutorial.

Also, any particular reason why those 4 aggregate functions go to a
different place to all the others?

The avg function is confusingly indexed only as "average", which
shouldn't really be a problem... unless someone types in "avg" into
their browser's find box. Maybe this should have "average" as a
primary term and "avg" as a secondary (with Pavel's 'median" function
to be added later). But next to this "average" index entry are links
to both the aggregate function sections, which are named identically.
I raised a similar issue to this for "privileges" in the index
previously.

--
Thom Brown
Twitter: @darkixion
IRC (freenode): dark_ixion
Registered Linux user: #516935

Excerpts from Thom Brown's message of mié sep 01 14:21:59 -0400 2010:
> Hi all,
>
> I noticed that all aggregate functions listed in the documentation
> index direct to a page listing all the aggregate functions and their
> usage, with the exception of count, max, min and sum, which direct to
> the aggregate function tutorial page. From the index, these sections
> are indistinguishable from one another since they share the same page
> name. I'm wondering if one should be named differently, like
> Aggregate Functions Tutorial.

+1 on using different titles. No opinion your particular suggestion,
but the TOC on the tutorial needs to be consistent as well.

> The avg function is confusingly indexed only as "average", which
> shouldn't really be a problem... unless someone types in "avg" into
> their browser's find box. Maybe this should have "average" as a
> primary term and "avg" as a secondary (with Pavel's 'median" function
> to be added later).

I think we should have index entries for function names, aggregate or
not. Perhaps <primary>avg</primary><secondary>aggregate function</> ?
Hmm, or maybe the other way around, so that all aggregates are listed
together in the index? Not sure. (but surely we don't want to have all
functions lumped together in a single "<primary>function</>").

For some reason I don't like <primary>average</><secondary>avg</>, but
then I don't like the current <primary>average</> either.

> But next to this "average" index entry are links
> to both the aggregate function sections, which are named identically.
> I raised a similar issue to this for "privileges" in the index
> previously.

Confusing index entries favor no one. +1 for fixes you can suggest.

--
Álvaro Herrera <alvherre(at)commandprompt(dot)com>
The PostgreSQL Company - Command Prompt, Inc.
PostgreSQL Replication, Consulting, Custom Development, 24x7 support

On 1 September 2010 19:57, Alvaro Herrera <alvherre(at)commandprompt(dot)com> wrote:
> Excerpts from Thom Brown's message of mié sep 01 14:21:59 -0400 2010:
>> The avg function is confusingly indexed only as "average", which
>> shouldn't really be a problem... unless someone types in "avg" into
>> their browser's find box.  Maybe this should have "average" as a
>> primary term and "avg" as a secondary (with Pavel's 'median" function
>> to be added later).
>
> I think we should have index entries for function names, aggregate or
> not.  Perhaps <primary>avg</primary><secondary>aggregate function</> ?
> Hmm, or maybe the other way around, so that all aggregates are listed
> together in the index?  Not sure.  (but surely we don't want to have all
> functions lumped together in a single "<primary>function</>").

I think the problem with that is if someone's scrolling down the page
looking for a function name alphabetically, they probably won't find
it if it's been bundled into a group. If they did want to see a list
of aggregate functions, they already have the option to look up
"aggregate functions > built-in" in the index.

> For some reason I don't like <primary>average</><secondary>avg</>, but
> then I don't like the current <primary>average</> either.

We could just replace that with <primary>avg</>, because at least then
it can be found by a browser's Find functionality.

--
Thom Brown
Twitter: @darkixion
IRC (freenode): dark_ixion
Registered Linux user: #516935

On Wed, Sep 1, 2010 at 2:21 PM, Thom Brown <thom(at)linux(dot)com> wrote:
> I noticed that all aggregate functions listed in the documentation
> index direct to a page listing all the aggregate functions and their
> usage, with the exception of count, max, min and sum, which direct to
> the aggregate function tutorial page.  From the index, these sections
> are indistinguishable from one another since they share the same page
> name.  I'm wondering if one should be named differently, like
> Aggregate Functions Tutorial.

Yeah, maybe. The thing is, many of the things in the tutorial-sql
chapter could be subject to similar confusion. Is there a way we can
make those show up differently in the index than they do in the table
of contents for that chapter?

> Also, any particular reason why those 4 aggregate functions go to a
> different place to all the others?

This just seems wildly inconsistent. I'd be inclined to make these
all point to the reference docs rather than the tutorial. Or else
point to both.

> The avg function is confusingly indexed only as "average", which
> shouldn't really be a problem... unless someone types in "avg" into
> their browser's find box.  Maybe this should have "average" as a
> primary term and "avg" as a secondary (with Pavel's 'median" function
> to be added later).

Sounds fine to me.

> But next to this "average" index entry are links
> to both the aggregate function sections, which are named identically.
> I raised a similar issue to this for "privileges" in the index
> previously.

This should be made consistent with whatever we do about the point two
paragraphs up.

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