From: Tom Lane <tgl@sss.pgh.pa.us>
To: Nathan Bossart <nathandbossart@gmail.com>
cc: "Thibaud W." <thibaud.walkowiak@dalibo.com>,
        pgsql-hackers@lists.postgresql.org
Subject: Re: Proposal: adding a better description in psql command about large
 objects
In-reply-to: <20220603152319.GA2627191@nathanxps13>
References: <43f0439c-df3e-a045-ac99-af33523cc2d4@dalibo.com>
 <20220602214625.GA2494933@nathanxps13>
 <2e872233-1642-439c-dd94-56fc25d398cb@dalibo.com>
 <20220603143921.GA2624579@nathanxps13> <216601.1654269131@sss.pgh.pa.us>
 <20220603152319.GA2627191@nathanxps13>
Comments: In-reply-to Nathan Bossart <nathandbossart@gmail.com>
	message dated "Fri, 03 Jun 2022 08:23:19 -0700"
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="----- =_aaaaaaaaaa0"
Content-ID: <272121.1654275368.0@sss.pgh.pa.us>
Date: Fri, 03 Jun 2022 12:56:20 -0400
Message-ID: <272177.1654275380@sss.pgh.pa.us>
Archived-At: 
 <https://www.postgresql.org/message-id/272177.1654275380%40sss.pgh.pa.us>
Precedence: bulk

------- =_aaaaaaaaaa0
Content-Type: text/plain; charset="us-ascii"
Content-ID: <272121.1654275368.1@sss.pgh.pa.us>

Nathan Bossart <nathandbossart@gmail.com> writes:
> On Fri, Jun 03, 2022 at 11:12:11AM -0400, Tom Lane wrote:
>> * While we're here, it seems like this whole group was placed at the
>> end because of add-it-to-the-end-itis, not because that was the
>> most logical place for it.  The other commands that interact with
>> the server are mostly further up.  My first thought is to move it
>> to just after the "Informational" group, but I'm not especially
>> set on that.  Making it not-last might make it harder to get away
>> with the inconsistent indentation, though.

> Another option could be to move it after the "Input/Output" section so that
> it's closer to some other commands that involve files.  I can't say I have
> a strong opinion about whether/where to move it, though.

Yeah, I thought of that choice too, but it ends up placing the
Large Objects section higher up the list than seems warranted on
frequency-of-use grounds.

After looking at the output I concluded that we'd be better off to
stick with the normal indentation amount, and break the lo_import
entry into two lines to make that work.  One reason for this is
that some translators might've already settled on a different
indentation amount in order to cope with translated parameter names,
and deviating from the normal here will just complicate their lives.
So that leaves me proposing v5.

(I also fixed the out-of-date line count in helpVariables.)

			regards, tom lane


------- =_aaaaaaaaaa0
Content-Type: text/x-diff;
	name*0="v5-0001-Add-descriptions-for-psql-s-large-object-backslas.p";
	name*1="atch"; charset="us-ascii"
Content-ID: <272121.1654275368.2@sss.pgh.pa.us>
Content-Description: 
 v5-0001-Add-descriptions-for-psql-s-large-object-backslas.patch
Content-Transfer-Encoding: quoted-printable

diff --git a/src/bin/psql/help.c b/src/bin/psql/help.c
index 49eb116f33..81a4739cda 100644
--- a/src/bin/psql/help.c
+++ b/src/bin/psql/help.c
@@ -163,7 +163,7 @@ slashUsage(unsigned short int pager)
 	 * Use "psql --help=3Dcommands | wc" to count correctly.  It's okay to c=
ount
 	 * the USE_READLINE line even in builds without that.
 	 */
-	output =3D PageOutput(138, pager ? &(pset.popt.topt) : NULL);
+	output =3D PageOutput(139, pager ? &(pset.popt.topt) : NULL);
 =

 	fprintf(output, _("General\n"));
 	fprintf(output, _("  \\copyright             show PostgreSQL usage and d=
istribution terms\n"));
@@ -272,6 +272,14 @@ slashUsage(unsigned short int pager)
 	fprintf(output, _("  \\z      [PATTERN]      same as \\dp\n"));
 	fprintf(output, "\n");
 =

+	fprintf(output, _("Large Objects\n"));
+	fprintf(output, _("  \\lo_export LOBOID FILE write large object to file\=
n"));
+	fprintf(output, _("  \\lo_import FILE [COMMENT]\n"
+					  "                         read large object from file\n"));
+	fprintf(output, _("  \\lo_list[+]            list large objects\n"));
+	fprintf(output, _("  \\lo_unlink LOBOID      delete a large object\n"));
+	fprintf(output, "\n");
+
 	fprintf(output, _("Formatting\n"));
 	fprintf(output, _("  \\a                     toggle between unaligned an=
d aligned output mode\n"));
 	fprintf(output, _("  \\C [STRING]            set table title, or unset i=
f none\n"));
@@ -318,13 +326,6 @@ slashUsage(unsigned short int pager)
 	fprintf(output, _("  \\prompt [TEXT] NAME    prompt user to set internal=
 variable\n"));
 	fprintf(output, _("  \\set [NAME [VALUE]]    set internal variable, or l=
ist all if no parameters\n"));
 	fprintf(output, _("  \\unset NAME            unset (delete) internal var=
iable\n"));
-	fprintf(output, "\n");
-
-	fprintf(output, _("Large Objects\n"));
-	fprintf(output, _("  \\lo_export LOBOID FILE\n"
-					  "  \\lo_import FILE [COMMENT]\n"
-					  "  \\lo_list[+]\n"
-					  "  \\lo_unlink LOBOID      large object operations\n"));
 =

 	ClosePager(output);
 }
@@ -346,7 +347,7 @@ helpVariables(unsigned short int pager)
 	 * Windows builds currently print one fewer line than non-Windows builds=
.
 	 * Using the larger number is fine.
 	 */
-	output =3D PageOutput(161, pager ? &(pset.popt.topt) : NULL);
+	output =3D PageOutput(163, pager ? &(pset.popt.topt) : NULL);
 =

 	fprintf(output, _("List of specially treated variables\n\n"));
 =


------- =_aaaaaaaaaa0--