Subject: SPI not defined.

From: PG Doc comments form <[email-masked]>
Date: Mon, 29 Jan 2018 21:52:46 +0000

The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/9.5/static/contrib-spi.html
Description:

In the appendix for Additional Supplied Modules there is a module spi.  If
you click through the page for that module it never defines what spi is.  If
you search for PostgreSQL spi you get the page that doesn't define it and
some other information on the PostgreSQL Server Programming Interface, which
I think is a different SPI.  I would recommend that the module page define
the spi acronym.

---

From: "David G. Johnston" <[email-masked]>
Date: Mon, 29 Jan 2018 15:07:06 -0700

On Monday, January 29, 2018, PG Doc comments form <[email-masked]>
wrote:

> I think is a different SPI.

No, SPI in that module is indeed "Server Programming Interface".

>
>   I would recommend that the module page define
>
the spi acronym.

Seems reasonable.

David J.

---

From: Bruce Momjian <[email-masked]>
Date: Mon, 29 Jan 2018 22:26:16 -0500

>       I would recommend that the module page define

How is the attached patch?

-- 
  Bruce Momjian  <[email-masked]>        http://momjian.us
  EnterpriseDB                             http://enterprisedb.com

+ As you are, so once was I.  As I am, so you will be. +
+                      Ancient Roman grave inscription +
diff --git a/doc/src/sgml/contrib-spi.sgml b/doc/src/sgml/contrib-spi.sgml
new file mode 100644
index 32c7105..2dc2d92
*** a/doc/src/sgml/contrib-spi.sgml
--- b/doc/src/sgml/contrib-spi.sgml
***************
*** 10,16 ****
  
   <para>
    The <application>spi</application> module provides several workable examples
!   of using SPI and triggers.  While these functions are of some value in
    their own right, they are even more useful as examples to modify for
    your own purposes.  The functions are general enough to be used
    with any table, but you have to specify table and field names (as described
--- 10,17 ----
  
   <para>
    The <application>spi</application> module provides several workable examples
!   of using the Server Programming Interface (<acronym>SPI</acronym>) and
!   triggers.  While these functions are of some value in
    their own right, they are even more useful as examples to modify for
    your own purposes.  The functions are general enough to be used
    with any table, but you have to specify table and field names (as described

---

From: "David G. Johnston" <[email-masked]>
Date: Mon, 29 Jan 2018 20:39:22 -0700

> How is the attached patch?
Maybe add a link to:

 https://www.postgresql.org/docs/10/static/spi.html

Also, on that page, the error handling mechanisms have been "in flux" since
8.0 ... ?

" This is not currently documented because the mechanisms required are
still in flux. "

David J.

---

From: Tom Lane <[email-masked]>
Date: Mon, 29 Jan 2018 22:51:59 -0500

> How is the attached patch?

Maybe also make that text into a hyperlink to the SPI manual chapter?

			regards, tom lane

---

From: Bruce Momjian <[email-masked]>
Date: Mon, 29 Jan 2018 22:54:51 -0500

On Mon, Jan 29, 2018 at 08:39:22PM -0700, David G. Johnston wrote:
> Also, on that page, the error handling mechanisms have been "in flux" since 8.0
> ... ?
> 
> " This is not currently documented because the mechanisms required are still in
> flux. "

OK, updated patch with both fixes.

  
   <para>
  
   <para>

---

From: Bruce Momjian <[email-masked]>
Date: Mon, 29 Jan 2018 22:55:12 -0500

> Maybe also make that text into a hyperlink to the SPI manual chapter?

Yes, that's what I just did in the new patch.

---

From: "David G. Johnston" <[email-masked]>
Date: Mon, 29 Jan 2018 20:58:10 -0700

> Yes, that's what I just did in the new patch.

​Your second attachment is the same as the first.

Dave​

---

From: Tom Lane <[email-masked]>
Date: Mon, 29 Jan 2018 22:58:32 -0500

> OK, updated patch with both fixes.

AFAICS that's the same patch you posted before.

			regards, tom lane

---

From: Bruce Momjian <[email-masked]>
Date: Mon, 29 Jan 2018 23:03:32 -0500

> ​Your second attachment is the same as the first.

Oops, here is the right one.

index 32c7105..844ea16
  
   <para>
--- 10,18 ----
  
   <para>
    The <application>spi</application> module provides several workable examples
!   of using the <link linkend="spi">Server Programming Interface</link>
!   (<acronym>SPI</acronym>) and triggers.  While these functions are of
!   some value in
    their own right, they are even more useful as examples to modify for
    your own purposes.  The functions are general enough to be used
    with any table, but you have to specify table and field names (as described
diff --git a/doc/src/sgml/spi.sgml b/doc/src/sgml/spi.sgml
new file mode 100644
index 1044892..0bac342
*** a/doc/src/sgml/spi.sgml
--- b/doc/src/sgml/spi.sgml
***************
*** 42,49 ****
    have documented error-return conventions.  Those conventions only apply
    for errors detected within the SPI functions themselves, however.)
    It is possible to recover control after an error by establishing your own
!   subtransaction surrounding SPI calls that might fail.  This is not currently
!   documented because the mechanisms required are still in flux.
   </para>
  
   <para>
--- 42,48 ----
    have documented error-return conventions.  Those conventions only apply
    for errors detected within the SPI functions themselves, however.)
    It is possible to recover control after an error by establishing your own
!   subtransaction surrounding SPI calls that might fail.
   </para>
  
   <para>

---

From: Bruce Momjian <[email-masked]>
Date: Wed, 31 Jan 2018 16:55:03 -0500

> Oops, here is the right one.

Done and backpatched through 9.3.  Thanks for the feedback.