Re: pg_dump --no-comments confusion

On 2024-11-04 16:13 +0100, Matthias van de Meent wrote:
> On Mon, 4 Nov 2024 at 15:41, Bruce Momjian <bruce(at)momjian(dot)us> wrote:
> >
> > Someone emailed me privately saying they were confused because they
> > thought pg_dump --no-comments would remove SQL comments, not the SQL
> > COMMENT commands. Is this something worth clarifying in our docs? I am
> > not even sure how I would express it. It currently says:
> >
> > --no-comments
> > Do not dump comments.
> >
> > We could change it to:
> >
> > --no-comments
> > Do not dump SQL COMMENT commands
>
> I think that'd be more confusing, as SQL comments are /* */. There is
> no SQL standard-prescribed COMMENT command (if our current docs are to
> be believed, I don't have a recent version of ISO 9075 to verify that
> claim).

I think Bruce's suggestion is pretty clear that it does not mean line or
block comments, but rather the COMMENT command. But I also think that
"SQL" in front of the command name is unnecessary because the man page
uses the "FOOBAR command" form throughout, e.g.:

--inserts
Dump data as INSERT commands [...]

Also, it doesn't really matter whether COMMENT is standard SQL. I guess
the sole purpose of --no-comment is to make the dump more portable. But
we don't mention that use case at all right now which would also apply
to --no-{publications,security-labels,subscriptions}.

> Maybe: "Do not dump database object comments",

I think that would be confusing because --verbose already reads "output
detailed object comments" which are in fact line comments.

--
Erik