From 80c2b8ef7ad6e610f5c7bdc61b827983a87110e2 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Sun, 24 Sep 2023 16:03:29 -0500 Subject: [PATCH v5 03/14] Better section heading for plpgsql exception trapping The docs seem to use "error" and "exception" interchangeably, perhaps 50% each. But they never say that the are the same thing, and in the larger world they are not. Errors tend to be something that drop on the floor and usually halt execution whereas exceptions can be trapped and give the programmer more control over the flow of the program. (Although, to be fair, exceptions are a subset of errors.) "Trapping Errors" is not a good section title for these reasons, and because when it comes to programmatically raising errors in Pl/PgSQL you don't, you raise exceptions. The current section heading does not stand out in a scan of the table of contents when you're looking for exception handling, IMHO. "Error Processing and Trapping Exceptions" is a little long but it does accurately reflect that the section is about how Pl/PgSQL behaves under error conditions with quite a lot about how the programmer can trap exceptions, affect the program's flow of control, and process information about errors. The "Exception" is at the end, and so stands out after the section title is read. (At least, according to my understanding, the end of a sentence is the most memorable.) I left "Error" in the title since the word "error" is used so frequently in the docs, and the section is also about what happens when there is any sort of PG error, not just those raised in user code. Error comes first to stand upon a visual scan of the table of contents. --- doc/src/sgml/plpgsql.sgml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml index 874578265e..127dd1b337 100644 --- a/doc/src/sgml/plpgsql.sgml +++ b/doc/src/sgml/plpgsql.sgml @@ -2756,7 +2756,7 @@ NOTICE: row = {10,11,12} - Trapping Errors + Error Processing and Trapping Exceptions exceptions -- 2.30.2