Clarify deleting comments and security labels in synopsis
Hi Hackers,
A user on IRC was confused about how to delete a security label using
the `SECURITY LABLEL ON … IS …` command, and looking at the docs I can
see why.
The synopsis just says `IS 'label'`, which implies that it can only be a
string. It's not until you read the description for `label` that you
see "or `NULL` to drop the security label." I propose making the
synopsis say `IS { 'label' | NULL }` to make it clear that it can be
NULL as well. The same applies to `COMMENT ON … IS …`, which I've also
changed similarly in the attached.
- ilmari
Attachments:
0001-Clarify-that-COMMENT-and-SECURITY-LABEL-can-be-set-t.patchtext/x-diffDownload+2-3
=?utf-8?Q?Dagfinn_Ilmari_Manns=C3=A5ker?= <ilmari@ilmari.org> writes:
A user on IRC was confused about how to delete a security label using
the `SECURITY LABLEL ON … IS …` command, and looking at the docs I can
see why.
The synopsis just says `IS 'label'`, which implies that it can only be a
string. It's not until you read the description for `label` that you
see "or `NULL` to drop the security label." I propose making the
synopsis say `IS { 'label' | NULL }` to make it clear that it can be
NULL as well. The same applies to `COMMENT ON … IS …`, which I've also
changed similarly in the attached.
Agreed; as-is, the syntax summary is not just confusing but outright
wrong.
I think we could go further and split the entry under Parameters
to match:
'text'
The new comment (must be a simple string literal,
not an expression).
NULL
Write NULL to drop the comment.
regards, tom lane
Tom Lane <tgl@sss.pgh.pa.us> writes:
=?utf-8?Q?Dagfinn_Ilmari_Manns=C3=A5ker?= <ilmari@ilmari.org> writes:
A user on IRC was confused about how to delete a security label using
the `SECURITY LABLEL ON … IS …` command, and looking at the docs I can
see why.The synopsis just says `IS 'label'`, which implies that it can only be a
string. It's not until you read the description for `label` that you
see "or `NULL` to drop the security label." I propose making the
synopsis say `IS { 'label' | NULL }` to make it clear that it can be
NULL as well. The same applies to `COMMENT ON … IS …`, which I've also
changed similarly in the attached.Agreed; as-is, the syntax summary is not just confusing but outright
wrong.I think we could go further and split the entry under Parameters
to match:'text'
The new comment (must be a simple string literal,
not an expression).NULL
Write NULL to drop the comment.
Makes sense. Something like the attached v2?
regards, tom lane
- ilmari
Attachments:
v2-0001-Clarify-that-COMMENT-and-SECURITY-LABEL-can-be-se.patchtext/x-diffDownload+24-9
=?utf-8?Q?Dagfinn_Ilmari_Manns=C3=A5ker?= <ilmari@ilmari.org> writes:
Tom Lane <tgl@sss.pgh.pa.us> writes:
Agreed; as-is, the syntax summary is not just confusing but outright
wrong.I think we could go further and split the entry under Parameters
to match:
Makes sense. Something like the attached v2?
WFM, will push.
regards, tom lane
Tom Lane <tgl@sss.pgh.pa.us> writes:
=?utf-8?Q?Dagfinn_Ilmari_Manns=C3=A5ker?= <ilmari@ilmari.org> writes:
Tom Lane <tgl@sss.pgh.pa.us> writes:
Agreed; as-is, the syntax summary is not just confusing but outright
wrong.I think we could go further and split the entry under Parameters
to match:Makes sense. Something like the attached v2?
WFM, will push.
Thanks!
regards, tom lane
- ilmari