X-Original-To: pgsql-docs-postgresql.org@localhost.postgresql.org Received: from localhost (unknown [64.117.224.130]) by svr1.postgresql.org (Postfix) with ESMTP id 03A70D1D996 for ; Tue, 26 Aug 2003 10:52:14 -0300 (ADT) Received: from svr1.postgresql.org ([64.117.224.193]) by localhost (neptune.hub.org [64.117.224.130]) (amavisd-new, port 10024) with ESMTP id 13467-07 for ; Tue, 26 Aug 2003 10:51:40 -0300 (ADT) Received: from bast.unixathome.org (bast.unixathome.org [66.11.174.150]) by svr1.postgresql.org (Postfix) with ESMTP id 0465FD1B56C for ; Tue, 26 Aug 2003 10:51:36 -0300 (ADT) Received: from wocker (wocker.unixathome.org [192.168.0.99]) by bast.unixathome.org (Postfix) with ESMTP id BE22F3D29; Tue, 26 Aug 2003 09:51:32 -0400 (EDT) From: "Dan Langille" To: Tom Lane , pgsql-docs@postgresql.org Date: Tue, 26 Aug 2003 09:52:20 -0400 MIME-Version: 1.0 Subject: Re: Do we need "Diagnostics" sections of SQL command reference pages? Cc: pgsql-docs@postgresql.org Message-ID: <3F4B2DD4.23482.19DE8A50@localhost> References: <3F4B2628.2121.19C09262@localhost> In-reply-to: <9357.1061905024@sss.pgh.pa.us> X-mailer: Pegasus Mail for Windows (v4.02a) Content-type: text/plain; charset=US-ASCII Content-transfer-encoding: 7BIT Content-description: Mail message body X-Virus-Scanned: by amavisd-new at postgresql.org X-Archive-Number: 200308/72 X-Sequence-Number: 1932 On 26 Aug 2003 at 9:37, Tom Lane wrote: > "Dan Langille" writes: > > On 26 Aug 2003 at 9:14, Tom Lane wrote: > >> http://developer.postgresql.org/docs/postgres/sql-createdatabase.html > > > The value I see in those message is it gives the reader more > > information about what can go wrong. The above example shows that > > you cannot use "create database" within a transaction. > > Sure, but that should have been stated in the command description. Agreed. If the command description contains enough information, the DIAGNOSTICS section is no longer needed. > > Also, the information under "ERROR: Could not initialize database > > directory." is pretty good. > > I chose this example deliberately, because it's one of very few pages > where there's actually nontrivial content in the Diagnostics section. > "could not initialize database directory" seems to me the only one > of these messages that requires more info (the "could not create > database directory" message now includes the kernel error code, so > it's sufficiently improved IMHO). What I'm inclined to do about it > is add a DETAIL field showing the exact "cp" command that failed, and > perhaps a HINT suggesting that people look in the postmaster's stderr > log to see cp's complaint. Not sure how to translate that to Windows, > but under Unix it should be sufficient no? For me, yes. I do like the idea of a DETAIL field. The more info the better. The HINT would be nice to have. -- Dan Langille : http://www.langille.org/