Thread: 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@commandprompt.com> The PostgreSQL Company - Command Prompt, Inc. PostgreSQL Replication, Consulting, Custom Development, 24x7 support
On 1 September 2010 19:57, Alvaro Herrera <alvherre@commandprompt.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@linux.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