public inbox for [email protected]help / color / mirror / Atom feed
Do we need "Diagnostics" sections of SQL command reference pages? 12+ messages / 6 participants [nested] [flat]
* Do we need "Diagnostics" sections of SQL command reference pages? @ 2003-08-25 21:37 Tom Lane <[email protected]> 0 siblings, 4 replies; 12+ messages in thread From: Tom Lane @ 2003-08-25 21:37 UTC (permalink / raw) To: pgsql-docs I'm starting to look at updating the docs to match 7.4 error message spellings. I find that a large part of the work I'll have to do is in updating the "Diagnostics" (formerly "Outputs") section of the command reference pages. I am wondering if it wouldn't be better to just rip out these sections entirely. They seem like nearly content-free fluff to me --- the listings of possible error messages are always incomplete, often out of date, and arguably useless. If there is an error message that's not clear enough by itself, we'd better fix the error message instead of putting a gloss on it in the reference page. Comments? regards, tom lane ^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: Do we need "Diagnostics" sections of SQL command reference pages? @ 2003-08-26 12:16 Bruno Wolff III <[email protected]> parent: Tom Lane <[email protected]> 3 siblings, 0 replies; 12+ messages in thread From: Bruno Wolff III @ 2003-08-26 12:16 UTC (permalink / raw) To: Tom Lane <[email protected]>; +Cc: pgsql-docs On Mon, Aug 25, 2003 at 17:37:50 -0400, Tom Lane <[email protected]> wrote: > I'm starting to look at updating the docs to match 7.4 error message > spellings. I find that a large part of the work I'll have to do is in > updating the "Diagnostics" (formerly "Outputs") section of the command > reference pages. I am wondering if it wouldn't be better to just rip > out these sections entirely. They seem like nearly content-free fluff > to me --- the listings of possible error messages are always incomplete, > often out of date, and arguably useless. If there is an error message > that's not clear enough by itself, we'd better fix the error message > instead of putting a gloss on it in the reference page. > > Comments? I think that a listing of possible error messages essentially indexed by command isn't very useful. However some of the documentation in that section is useful. In particular the information for INSERT covers stuff that isn't self explanatory in the output message. ^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: Do we need "Diagnostics" sections of SQL command reference pages? @ 2003-08-26 12:26 Dan Langille <[email protected]> parent: Tom Lane <[email protected]> 3 siblings, 2 replies; 12+ messages in thread From: Dan Langille @ 2003-08-26 12:26 UTC (permalink / raw) To: Tom Lane <[email protected]>; +Cc: pgsql-docs On 25 Aug 2003 at 17:37, Tom Lane wrote: > I'm starting to look at updating the docs to match 7.4 error message > spellings. I find that a large part of the work I'll have to do is in > updating the "Diagnostics" (formerly "Outputs") section of the command > reference pages. Do you have a URL for that. I was looking at http://developer.postgresql.org/docs/postgres/index.html and didn't find it. > I am wondering if it wouldn't be better to just rip > out these sections entirely. They seem like nearly content-free fluff > to me --- the listings of possible error messages are always incomplete, > often out of date, and arguably useless. If there is an error message > that's not clear enough by itself, we'd better fix the error message > instead of putting a gloss on it in the reference page. > > Comments? I have never been a fan of error codes. I think that the error messages should contain enough information to fix the error. It saves the reader time and reduces the load on support mechanisms (e.g. the mailing lists). -- Dan Langille : http://www.langille.org/ ^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: Do we need "Diagnostics" sections of SQL command reference pages? @ 2003-08-26 13:14 Tom Lane <[email protected]> parent: Dan Langille <[email protected]> 1 sibling, 0 replies; 12+ messages in thread From: Tom Lane @ 2003-08-26 13:14 UTC (permalink / raw) To: Dan Langille <[email protected]>; +Cc: pgsql-docs "Dan Langille" <[email protected]> writes: > On 25 Aug 2003 at 17:37, Tom Lane wrote: >> I'm starting to look at updating the docs to match 7.4 error message >> spellings. I find that a large part of the work I'll have to do is in >> updating the "Diagnostics" (formerly "Outputs") section of the command >> reference pages. > Do you have a URL for that. Any of the SQL command reference pages, eg http://developer.postgresql.org/docs/postgres/sql-createdatabase.html regards, tom lane ^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: Do we need "Diagnostics" sections of SQL command reference pages? @ 2003-08-26 13:19 Dan Langille <[email protected]> parent: Dan Langille <[email protected]> 1 sibling, 2 replies; 12+ messages in thread From: Dan Langille @ 2003-08-26 13:19 UTC (permalink / raw) To: Tom Lane <[email protected]>; +Cc: pgsql-docs On 26 Aug 2003 at 9:14, Tom Lane wrote: > "Dan Langille" <[email protected]> writes: > > On 25 Aug 2003 at 17:37, Tom Lane wrote: > >> I'm starting to look at updating the docs to match 7.4 error message > >> spellings. I find that a large part of the work I'll have to do is in > >> updating the "Diagnostics" (formerly "Outputs") section of the command > >> reference pages. > > > Do you have a URL for that. > > Any of the SQL command reference pages, eg > http://developer.postgresql.org/docs/postgres/sql-createdatabase.html Thanks. I was looking for a single section. 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. Also, the information under "ERROR: Could not initialize database directory." is pretty good. -- Dan Langille : http://www.langille.org/ ^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: Do we need "Diagnostics" sections of SQL command reference pages? @ 2003-08-26 13:37 Tom Lane <[email protected]> parent: Dan Langille <[email protected]> 1 sibling, 1 reply; 12+ messages in thread From: Tom Lane @ 2003-08-26 13:37 UTC (permalink / raw) To: Dan Langille <[email protected]>; +Cc: pgsql-docs "Dan Langille" <[email protected]> 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. > 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? regards, tom lane ^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: Do we need "Diagnostics" sections of SQL command reference pages? @ 2003-08-26 13:52 Dan Langille <[email protected]> parent: Dan Langille <[email protected]> 1 sibling, 0 replies; 12+ messages in thread From: Dan Langille @ 2003-08-26 13:52 UTC (permalink / raw) To: Tom Lane <[email protected]>; pgsql-docs; +Cc: pgsql-docs On 26 Aug 2003 at 9:37, Tom Lane wrote: > "Dan Langille" <[email protected]> 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/ ^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: Do we need "Diagnostics" sections of SQL command reference pages? @ 2003-08-27 12:51 Chris M <[email protected]> parent: Tom Lane <[email protected]> 0 siblings, 0 replies; 12+ messages in thread From: Chris M @ 2003-08-27 12:51 UTC (permalink / raw) To: pgsql-docs "Tom Lane" <[email protected]> Write news:[email protected]... > "Dan Langille" <[email protected]> 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. > > > 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, Windows port may use "copy", "xcopy" to copy files. In Windows, "copy" is not so powerful as "xcopy". But I don't think using OS specific shell commands a good idea. If environment variable PATH is not set correctly, using these commands may cause a fail. > but under Unix it should be sufficient no? > > regards, tom lane > > ---------------------------(end of broadcast)--------------------------- > TIP 9: the planner will ignore your desire to choose an index scan if your > joining column's datatypes do not match > ^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: Do we need "Diagnostics" sections of SQL command reference pages? @ 2003-09-03 20:06 Josh Berkus <[email protected]> parent: Tom Lane <[email protected]> 3 siblings, 1 reply; 12+ messages in thread From: Josh Berkus @ 2003-09-03 20:06 UTC (permalink / raw) To: Tom Lane <[email protected]>; pgsql-docs Tom, > I'm starting to look at updating the docs to match 7.4 error message > spellings. I find that a large part of the work I'll have to do is in > updating the "Diagnostics" (formerly "Outputs") section of the command > reference pages. I am wondering if it wouldn't be better to just rip > out these sections entirely. They seem like nearly content-free fluff > to me --- the listings of possible error messages are always incomplete, > often out of date, and arguably useless. If there is an error message > that's not clear enough by itself, we'd better fix the error message > instead of putting a gloss on it in the reference page. > > Comments? I agree that we don't need descriptions of the meaning of each error message in the command documentation. However, the listing of potential error messages is *very* useful to application coders for doing automated handling of errors. Since we are now supporting SQLSTATE responses, perhaps we could have error code ranges for the commands? Or is that totally unreasonable? -- -Josh Berkus Aglio Database Solutions San Francisco ^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: Do we need "Diagnostics" sections of SQL command reference pages? @ 2003-09-03 21:31 Tom Lane <[email protected]> parent: Josh Berkus <[email protected]> 0 siblings, 0 replies; 12+ messages in thread From: Tom Lane @ 2003-09-03 21:31 UTC (permalink / raw) To: [email protected]; +Cc: pgsql-docs Josh Berkus <[email protected]> writes: > I agree that we don't need descriptions of the meaning of each error message > in the command documentation. > However, the listing of potential error messages is *very* useful to > application coders for doing automated handling of errors. Since we are now > supporting SQLSTATE responses, perhaps we could have error code ranges for > the commands? Or is that totally unreasonable? It seems completely impractical to guarantee that any particular command can produce only some-small-subset of all the possible errors. There are too many layers of code involved in handling any SQL command. regards, tom lane ^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: Do we need "Diagnostics" sections of SQL command reference @ 2003-09-03 22:12 Peter Eisentraut <[email protected]> parent: Tom Lane <[email protected]> 3 siblings, 1 reply; 12+ messages in thread From: Peter Eisentraut @ 2003-09-03 22:12 UTC (permalink / raw) To: Tom Lane <[email protected]>; +Cc: pgsql-docs Tom Lane writes: > I'm starting to look at updating the docs to match 7.4 error message > spellings. I find that a large part of the work I'll have to do is in > updating the "Diagnostics" (formerly "Outputs") section of the command > reference pages. I am wondering if it wouldn't be better to just rip > out these sections entirely. I agree with ripping out the messages part, but it might be useful to show the completion tag somewhere, especially in cases where it contains additional information (e.g., UPDATE). -- Peter Eisentraut [email protected] ^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: Do we need "Diagnostics" sections of SQL command reference pages? @ 2003-09-03 22:25 Tom Lane <[email protected]> parent: Peter Eisentraut <[email protected]> 0 siblings, 0 replies; 12+ messages in thread From: Tom Lane @ 2003-09-03 22:25 UTC (permalink / raw) To: Peter Eisentraut <[email protected]>; +Cc: pgsql-docs Peter Eisentraut <[email protected]> writes: > I agree with ripping out the messages part, but it might be useful to show > the completion tag somewhere, especially in cases where it contains > additional information (e.g., UPDATE). I'll make sure the completion tag is documented anywhere it's not simply the command name. regards, tom lane ^ permalink raw reply [nested|flat] 12+ messages in thread
end of thread, other threads:[~2003-09-03 22:25 UTC | newest] Thread overview: 12+ messages (download: mbox mbox.gz follow: Atom feed) -- links below jump to the message on this page -- 2003-08-25 21:37 Do we need "Diagnostics" sections of SQL command reference pages? Tom Lane <[email protected]> 2003-08-26 12:16 ` Bruno Wolff III <[email protected]> 2003-08-26 12:26 ` Dan Langille <[email protected]> 2003-08-26 13:14 ` Tom Lane <[email protected]> 2003-08-26 13:19 ` Dan Langille <[email protected]> 2003-08-26 13:37 ` Tom Lane <[email protected]> 2003-08-27 12:51 ` Chris M <[email protected]> 2003-08-26 13:52 ` Dan Langille <[email protected]> 2003-09-03 20:06 ` Josh Berkus <[email protected]> 2003-09-03 21:31 ` Tom Lane <[email protected]> 2003-09-03 22:12 ` Re: Do we need "Diagnostics" sections of SQL command reference Peter Eisentraut <[email protected]> 2003-09-03 22:25 ` Tom Lane <[email protected]>
This inbox is served by agora; see mirroring instructions for how to clone and mirror all data and code used for this inbox