Horton

Thread

Commits

  1. Doc: clarify use of NULL to drop comments and security labels.

  1. Clarify deleting comments and security labels in synopsis

    Dagfinn Ilmari Mannsåker <ilmari@ilmari.org> — 2023-01-31T17:07:06Z

    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

  2. Re: Clarify deleting comments and security labels in synopsis

    Tom Lane <tgl@sss.pgh.pa.us> — 2023-01-31T17:35:26Z

    =?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

  3. Re: Clarify deleting comments and security labels in synopsis

    Dagfinn Ilmari Mannsåker <ilmari@ilmari.org> — 2023-01-31T18:07:15Z

    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

  4. Re: Clarify deleting comments and security labels in synopsis

    Tom Lane <tgl@sss.pgh.pa.us> — 2023-01-31T18:52:21Z

    =?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

  5. Re: Clarify deleting comments and security labels in synopsis

    Dagfinn Ilmari Mannsåker <ilmari@ilmari.org> — 2023-02-01T10:50:42Z

    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