On Feb 4, 2009, at 9:33 AM, Robert Haas wrote:
Just to play devil's advocate, I have used the PostgreSQL documentation for years and have long understood that the references pages are the place to go if you really need the nitty-gritty on how a particular command works. I agree that you might not realize this if you just casually Google your way in, but I can't imagine that problem is fixable. You'll just end up with a zillion cross-references that will, overall, reduce the clarity and readability of the documentation, which is overall very good.
I think that all pages that seem to document particular features should cross-reference the reference pages in section VI, but not necessarily vice-versa. I don't think that's asking for a lot. If you're reading the narrative section, um, narratively, then you'll see lots of "Look here for more on this topic when you're ready," and that will be much more useful for the search-result-hit readers, too.
For myself, I've always used the reference documentation, and kind of never really understood where some of the extra documentation of certain features, like LIMIT/OFFSET, lived. I never realized there was a narrative section. As a technically-minded geek, I go right to the reference, and the other stuff is kind of a weird bonus that comes up when I do a search.
So unless you're reading the documentation like a bound book, or had glanced through each of the top-level pages of the TOC to familiarize yourself with the structure, I'm not sure anyone would really understand how the non-reference documentation was organized, or that it wasn't meant to be authoritative.
Still, the queries-limit.html page includes this statement: "OFFSET 0 is the same as omitting the OFFSET clause." I don't see that there would be anything bad or confusing about changing it to read this way: "OFFSET 0 is the same as omitting the OFFSET clause, and LIMIT NULL is the same as omitting the LIMIT clause." In fact, it seems nicely symmetric.
My patch had done that, basically. The page mentions OFFSET ALL, and I had just changed it to read OFFSET ALL or OFFSET NULL. Three little words. :-)
Best, David -- Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-hackers
