From: Tom Lane <tgl@sss.pgh.pa.us>
To: "David G. Johnston" <david.g.johnston@gmail.com>
cc: Michael Paquier <michael@paquier.xyz>,
        =?UTF-8?B?5pel5ZCR5YWF?= <mitsuru.hinata.5432@gmail.com>,
        pgsql-docs@lists.postgresql.org
Subject: Re: A minor bug in the doc of "SQL Functions Returning Sets" in
 xfunc.sgml.
In-reply-to: 
 <CAKFQuwa3nNETFm23VjbX+2=aaBK7Am5Q0ZE3OsBXvYLorLw+Mg@mail.gmail.com>
References: 
 <CAF-2iM_9-2a8PijHoHbS6ZFFV=tziOx8TDo4j+YGDAbsTApk4w@mail.gmail.com>
 <ZpnLEUUNxy-LP_lY@paquier.xyz>
 <CAKFQuwa3nNETFm23VjbX+2=aaBK7Am5Q0ZE3OsBXvYLorLw+Mg@mail.gmail.com>
Comments: In-reply-to "David G. Johnston" <david.g.johnston@gmail.com>
	message dated "Thu, 18 Jul 2024 20:55:40 -0700"
MIME-Version: 1.0
Content-Type: text/plain; charset="UTF-8"
Content-ID: <4046197.1721361924.1@sss.pgh.pa.us>
Content-Transfer-Encoding: quoted-printable
Date: Fri, 19 Jul 2024 00:05:24 -0400
Message-ID: <4046198.1721361924@sss.pgh.pa.us>
Archived-At: 
 <https://www.postgresql.org/message-id/4046198.1721361924%40sss.pgh.pa.us>
Precedence: bulk

"David G. Johnston" <david.g.johnston@gmail.com> writes:
> On Thu, Jul 18, 2024 at 7:10=E2=80=AFPM Michael Paquier <michael@paquier=
.xyz> wrote:
>> Not sure that this is worth changing.  The examples work OK when taken
>> in isolation or are able to demonstrate the point they want to show.
>> In short, not all these queries are here to be compatible with the
>> contents in the same area.  See for example the case of the "nodes"
>> table on the same page, created nowhere.  "tab" is just a more generic
>> table name that's more spread.

> Clearly this page repeatedly expects tab.x to exist; and for these queri=
es
> to be executable.  This seems like the least invasive way to make that
> expectation reality.

I'm with Michael here.  Only in the tutorial do we expect there to be
a continuing thread of commands that you can just copy-and-paste and
expect to work.  I do not think it's reasonable to extend that policy
to the rest of the manual: in other places, there are too many
distinct topics under consideration and too much reason to make
localized changes.

			regards, tom lane