Re: LIMIT NULL - Mailing list pgsql-hackers

On Wednesday 04 February 2009 8:41:55 am Svenne Krap wrote:
> Andrew Dunstan wrote:
> >> Me neither. I wonder how many other long term users (I have used pgsql
> >> for more than a decade - 6.2 was my first version if memory serves)
> >> and have never caught that nuance either.
> >>
> >> Maybe that should be printed as a note on the "narrative description
> >> pages".. something like: "Note this is a simplified introduction to
> >> the subject. For authorative description please see topic x in section
> >> y (and link to it of course ;))
> >
> > In effect it does say that - perhaps not quite as explicitly as you
> > might have wanted. It says: "The information in this part is presented
> > in a narrative fashion in topical units. Readers looking for a
> > complete description of a particular command should look into Part VI.
> > " (the "PART VI" is a link).
>
> Well... I meant on EVERY single page outside section VI (or whatever is
> considered cannonical)
>
> I believe most users today search instead of browse documentation... I
> certainly do... that I have a decade of postgresql experience just helps
> me to know that section VI.I is extremly important (but I learned that
> through trial and error not by reading a small hint).
>
> If I google "postgresql limit" the second link links to
> http://www.postgresql.org/docs/8.3/interactive/queries-limit.html (for
> some reason google strongly prefers version 7.3).
> That page (which is the first you see if you search your way in) gives
> me the following impressions (i.e. given my information gathering
> heuristics):
> - domain postgresql.org (=official)
> - in the page title it states: PostgreSQL 8.3.5 Documentation  (=yeah,
> right place)
> - Chapter 7. Queries (=reasonable)
> - 7.6. LIMIT and OFFSET (= home free ;)
>
> Which gives me every indication that I am the right place. Nowhere on
> this page is the note, that there exists a better place (experience has
> shown me, that the SELECT page in the SQL reference is far more
> detailed, but that is unknown for a newbie user).

Exactly what lead me to my conclusions.
I picked up PG during the 8.0 betas - so I've not been around too long, but 
I've done enough that I no longer consider myself a "newbie user" ...

For the purpose of providing a use case from some random user:
I might have also arrived at the queries-limit page from:
http://www.postgresql.org/docs/current/static/
then clicking on II.7. taking me to:
http://www.postgresql.org/docs/current/static/queries.html
then clicking on 7.6, taking me to:
http://www.postgresql.org/docs/current/static/queries-limit.html

None of those pages say anything about the depth which the subject is covered, 
or the status of the page as "reference".

Of all the (apparently reference) docs I've read, I've never arrived at them 
through VI. Reference at 
http://www.postgresql.org/docs/current/static/reference.html

So this is very educating for me - would it be out of line to ask, in this 
forum, how one such as myself would know when arriving at 
http://www.postgresql.org/docs/8.3/interactive/queries-limit.html from Google 
or via the above described steps that the page is a not meant to be reference 
only?  Further, when one starts at the top of 
<http://www.postgresql.org/docs/current/static/> and starts reading down, what 
leads one to the reference page (at section VI) so that they may see that 
statement about the depth of coverage when the topic they're looking for is in 
section II?