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).
What I would like is that EVERY page, that is considered non-cannonical,
for the sake of useability has an end-note, that a better (more detailed
and more "correct") place exists and an indication of where to go..
which I believe would be
http://www.postgresql.org/docs/8.3/interactive/sql-select.html in the
choosen example.
/Svenne