[PATCH] Add ACL (Access Control List) acronym

On Mon, Jun 24, 2024 at 02:32:27PM +0200, Joel Jacobson wrote:

This patch is based on a suggestion from a separate thread [1]:

On Mon, Jun 24, 2024, at 01:46, Michael Paquier wrote:

Rather unrelated to this patch, still this patch makes the situation
more complicated in the docs, but wouldn't it be better to add ACL as
a term in acronyms.sql, and reuse it here? It would be a doc-only
patch that applies on top of the rest (could be on a new thread of its
own), with some <acronym> markups added where needed.

Sounds reasonable to me.

+ <ulink url="https://en.wikipedia.org/wiki/Access_Control_List&quot;&gt;Access Control List, i.e. privileges list</ulink>

I think we could omit "i.e. privileges list."

--
nathan

On Mon, Jun 24, 2024 at 8:44 AM Nathan Bossart <nathandbossart@gmail.com>
wrote:

On Mon, Jun 24, 2024 at 02:32:27PM +0200, Joel Jacobson wrote:

This patch is based on a suggestion from a separate thread [1]:

On Mon, Jun 24, 2024, at 01:46, Michael Paquier wrote:

Rather unrelated to this patch, still this patch makes the situation
more complicated in the docs, but wouldn't it be better to add ACL as
a term in acronyms.sql, and reuse it here? It would be a doc-only
patch that applies on top of the rest (could be on a new thread of its
own), with some <acronym> markups added where needed.

Sounds reasonable to me.

+1

+ <ulink url="https://en.wikipedia.org/wiki/Access_Control_List&quot;&gt;Access
Control List, i.e. privileges list</ulink>

I think we could omit "i.e. privileges list."

Agreed. Between the docs and code we say "privileges list" once and that
refers to the dumputIls description of the arguments to grant. As the
acronym page now defines the term using fundamentals, introducing another
term not used elsewhere seems undesirable.

Observations:
We are referencing a disambiguation page. We never actually spell out ACL
anywhere so we might as well just reference what Wikipedia believes is the
expected spelling.

The page we link to uses "permissions" while we consistently use
"privileges" to describe the contents of the list. This seems like an
obvious synonym, but as the point of these is to formally define things,
pointing this equivalence is worth considering.

David J.

On Mon, Jun 24, 2024, at 18:02, David G. Johnston wrote:

On Mon, Jun 24, 2024 at 8:44 AM Nathan Bossart <nathandbossart@gmail.com> wrote:

I think we could omit "i.e. privileges list."

Agreed. Between the docs and code we say "privileges list" once and
that refers to the dumputIls description of the arguments to grant. As
the acronym page now defines the term using fundamentals, introducing
another term not used elsewhere seems undesirable.

New version attached.

Observations:
We are referencing a disambiguation page. We never actually spell out
ACL anywhere so we might as well just reference what Wikipedia believes
is the expected spelling.

The page we link to uses "permissions" while we consistently use
"privileges" to describe the contents of the list. This seems like an
obvious synonym, but as the point of these is to formally define
things, pointing this equivalence is worth considering.

I like this idea. How could this be implemented in the docs? Maybe a <note>...</note> for ACL in acronyms.sgml?

/Joel

On Mon, Jun 24, 2024 at 12:46 PM Joel Jacobson <joel@compiler.org> wrote:

On Mon, Jun 24, 2024, at 18:02, David G. Johnston wrote:

The page we link to uses "permissions" while we consistently use
"privileges" to describe the contents of the list. This seems like an
obvious synonym, but as the point of these is to formally define
things, pointing this equivalence is worth considering.

I like this idea. How could this be implemented in the docs? Maybe a
<note>...</note> for ACL in acronyms.sgml?

Add a second <para> under the one holding the link?

David J.

On Mon, Jun 24, 2024, at 21:51, David G. Johnston wrote:

On Mon, Jun 24, 2024 at 12:46 PM Joel Jacobson <joel@compiler.org> wrote:

On Mon, Jun 24, 2024, at 18:02, David G. Johnston wrote:

The page we link to uses "permissions" while we consistently use
"privileges" to describe the contents of the list. This seems like an
obvious synonym, but as the point of these is to formally define
things, pointing this equivalence is worth considering.

I like this idea. How could this be implemented in the docs? Maybe a <note>...</note> for ACL in acronyms.sgml?

Add a second <para> under the one holding the link?

How about?

+     <para>
+      The linked page uses "permissions" while we consistently use the synonym
+      "privileges", to describe the contents of the list. For avoidance of
+      doubt and clarity, these two terms are equivalent in the
+      <productname>PostgreSQL</productname> documentation.
+     </para>

/Joel

On Mon, Jun 24, 2024 at 1:49 PM Joel Jacobson <joel@compiler.org> wrote:

How about?

+     <para>
+      The linked page uses "permissions" while we consistently use the
synonym
+      "privileges", to describe the contents of the list. For avoidance of
+      doubt and clarity, these two terms are equivalent in the
+      <productname>PostgreSQL</productname> documentation.
+     </para>

/Joel

I really dislike "For avoidance of doubt and clarity" - and in terms of
being equivalent the following seems like a more accurate description of
reality.

The PostgreSQL documentation, and code, refers to the specifications within
the ACL as "privileges". This has the same meaning as "permissions" on the
linked page. Generally if we say "permissions" we are referring to
something that is not covered by the ACL. In routine communication the two
words are often used interchangeably.

David J.

On Mon, Jun 24, 2024, at 23:15, David G. Johnston wrote:

I really dislike "For avoidance of doubt and clarity" - and in terms of
being equivalent the following seems like a more accurate description
of reality.

The PostgreSQL documentation, and code, refers to the specifications
within the ACL as "privileges". This has the same meaning as
"permissions" on the linked page. Generally if we say "permissions" we
are referring to something that is not covered by the ACL. In routine
communication the two words are often used interchangeably.

Thanks, much better. New version attached.

/Joel

On Tue, Jun 25, 2024 at 12:20:20AM +0200, Joel Jacobson wrote:

Thanks, much better. New version attached.

+      The <productname>PostgreSQL</productname> documentation, and code, refers
+      to the specifications within the ACL as "privileges".  This has the same
+      meaning as "permissions" on the linked page.  Generally if we say 

Hmm? A privilege is a property that is part of an ACL, which is
itself a set made of object types, roles and privileges. This entire
paragraph is unnecessary IMO, let's keep it simple with only a
reference link to the wiki page.

v1 is fine without the "privileges list" part mentioned by Nathan in
the first reply.
--
Michael

On Tue, Jun 25, 2024, at 07:11, Michael Paquier wrote:

On Tue, Jun 25, 2024 at 12:20:20AM +0200, Joel Jacobson wrote:

Thanks, much better. New version attached.

+      The <productname>PostgreSQL</productname> documentation, and code, refers
+      to the specifications within the ACL as "privileges".  This has the same
+      meaning as "permissions" on the linked page.  Generally if we say 

Hmm? A privilege is a property that is part of an ACL, which is
itself a set made of object types, roles and privileges. This entire
paragraph is unnecessary IMO, let's keep it simple with only a
reference link to the wiki page.

v1 is fine without the "privileges list" part mentioned by Nathan in
the first reply.

v2 is exactly that, but renamed and attached, so we have an entry this was the last version.

/Joel

On Tue, Jun 25, 2024 at 08:10:24AM +0200, Joel Jacobson wrote:

On Tue, Jun 25, 2024, at 07:11, Michael Paquier wrote:

v1 is fine without the "privileges list" part mentioned by Nathan in
the first reply.

v2 is exactly that, but renamed and attached, so we have an entry this
was the last version.

LGTM

--
nathan

On Tue, Jun 25, 2024 at 11:55:03AM -0500, Nathan Bossart wrote:

On Tue, Jun 25, 2024 at 08:10:24AM +0200, Joel Jacobson wrote:

On Tue, Jun 25, 2024, at 07:11, Michael Paquier wrote:

v1 is fine without the "privileges list" part mentioned by Nathan in
the first reply.

v2 is exactly that, but renamed and attached, so we have an entry this
was the last version.

LGTM

Fine by me as well. I guess I'll just apply that once v18 opens up.
--
Michael

On Tue, Jun 25, 2024 at 5:30 PM Michael Paquier <michael@paquier.xyz> wrote:

On Tue, Jun 25, 2024 at 11:55:03AM -0500, Nathan Bossart wrote:

On Tue, Jun 25, 2024 at 08:10:24AM +0200, Joel Jacobson wrote:

On Tue, Jun 25, 2024, at 07:11, Michael Paquier wrote:

v1 is fine without the "privileges list" part mentioned by Nathan in
the first reply.

v2 is exactly that, but renamed and attached, so we have an entry this
was the last version.

LGTM

Fine by me as well. I guess I'll just apply that once v18 opens up.

Fine by me. We aren't consistent enough about all this to try and be

authoritative.

Though there was no comment on the fact we should be linking to:

https://en.wikipedia.org/wiki/Access-control_list

not:

https://en.wikipedia.org/wiki/Access_Control_List

to avoid the dis-ambiguation redirect.

If we are making wikipedia our authority we might as well use their
standard for naming.

David J.

On Mon, Jun 24, 2024 at 10:11 PM Michael Paquier <michael@paquier.xyz>
wrote:

On Tue, Jun 25, 2024 at 12:20:20AM +0200, Joel Jacobson wrote:

Thanks, much better. New version attached.

+      The <productname>PostgreSQL</productname> documentation, and code,
refers
+      to the specifications within the ACL as "privileges".  This has the
same
+      meaning as "permissions" on the linked page.  Generally if we say

Hmm? A privilege is a property that is part of an ACL, which is
itself a set made of object types, roles and privileges.

So, an ACL is a collection of composite typed things (grantor, grantee,
privileges) and the type name for that composite type is "permission".
That does clear things up, even if we tend to use privilege in cases where
permission is meant.

David J.

On Tue, Jun 25, 2024 at 05:59:01PM -0700, David G. Johnston wrote:

Though there was no comment on the fact we should be linking to:

https://en.wikipedia.org/wiki/Access-control_list

not:

https://en.wikipedia.org/wiki/Access_Control_List

to avoid the dis-ambiguation redirect.

+1

--
nathan

On Wed, Jun 26, 2024, at 02:59, David G. Johnston wrote:

Though there was no comment on the fact we should be linking to:

https://en.wikipedia.org/wiki/Access-control_list

not:

https://en.wikipedia.org/wiki/Access_Control_List

to avoid the dis-ambiguation redirect.

If we are making wikipedia our authority we might as well use their
standard for naming.

Good point.

Want me to fix that or will the committer handle that?

I found some more similar cases in acronyms.sgml.

-https://en.wikipedia.org/wiki/Pluggable_Authentication_Modules
+https://en.wikipedia.org/wiki/Pluggable_authentication_module
-https://en.wikipedia.org/wiki/Data_Manipulation_Language
+https://en.wikipedia.org/wiki/Data_manipulation_language
-https://en.wikipedia.org/wiki/OLTP
+https://en.wikipedia.org/wiki/Online_transaction_processing
-https://en.wikipedia.org/wiki/Data_Definition_Language
+https://en.wikipedia.org/wiki/Data_definition_language
-https://en.wikipedia.org/wiki/ORDBMS
+https://en.wikipedia.org/wiki/Object%E2%80%93relational_database
-https://en.wikipedia.org/wiki/GMT
+https://en.wikipedia.org/wiki/Greenwich_Mean_Time
-https://en.wikipedia.org/wiki/Relational_database_management_system
+https://en.wikipedia.org/wiki/Relational_database#RDBMS
-https://en.wikipedia.org/wiki/Olap
-https://en.wikipedia.org/wiki/Issn
+https://en.wikipedia.org/wiki/Online_analytical_processing
+https://en.wikipedia.org/wiki/ISSN
-https://en.wikipedia.org/wiki/System_V
+https://en.wikipedia.org/wiki/UNIX_System_V
-https://en.wikipedia.org/wiki/Visual_C++
+https://en.wikipedia.org/wiki/Microsoft_Visual_C%2B%2B
-https://en.wikipedia.org/wiki/SGML
+https://en.wikipedia.org/wiki/Standard_Generalized_Markup_Language
-https://en.wikipedia.org/wiki/Ascii
+https://en.wikipedia.org/wiki/ASCII
-https://en.wikipedia.org/wiki/Dbms
+https://en.wikipedia.org/wiki/Database#Database_management_system
-https://en.wikipedia.org/wiki/Git_(software)
+https://en.wikipedia.org/wiki/Git
-https://en.wikipedia.org/wiki/Utf8
+https://en.wikipedia.org/wiki/UTF-8
-https://en.wikipedia.org/wiki/Secure_Sockets_Layer
+https://en.wikipedia.org/wiki/Transport_Layer_Security#SSL_1.0,_2.0,_and_3.0

Below is the script I used to find them,
which also reports some additional false positives:

```
#!/bin/bash

export LC_ALL=C
wget -q -O acronyms.html https://www.postgresql.org/docs/current/acronyms.html
urls=$(grep -o 'https://[^&quot;]*&#39; acronyms.html)
output_file="canonical_urls.txt"

$output_file

extract_canonical() {
local url=$1
canonical=$(curl -s $url | sed -n 's/.*<link rel="canonical" href="\([^"]*\)".*/\1/p')
if [[ -n "$canonical" && "$canonical" != "$url" ]]; then
echo "-$url" >> $output_file
echo "+$canonical" >> $output_file
fi
}

for url in $urls; do
extract_canonical $url &
done

wait

cat $output_file
```

/Joel

On Wed, Jun 26, 2024 at 7:52 AM Joel Jacobson <joel@compiler.org> wrote:

On Wed, Jun 26, 2024, at 02:59, David G. Johnston wrote:

Though there was no comment on the fact we should be linking to:

https://en.wikipedia.org/wiki/Access-control_list

not:

https://en.wikipedia.org/wiki/Access_Control_List

to avoid the dis-ambiguation redirect.

If we are making wikipedia our authority we might as well use their
standard for naming.

Good point.

Want me to fix that or will the committer handle that?

I found some more similar cases in acronyms.sgml.

-https://en.wikipedia.org/wiki/Pluggable_Authentication_Modules
+https://en.wikipedia.org/wiki/Pluggable_authentication_module
-https://en.wikipedia.org/wiki/Data_Manipulation_Language
+https://en.wikipedia.org/wiki/Data_manipulation_language
-https://en.wikipedia.org/wiki/OLTP
+https://en.wikipedia.org/wiki/Online_transaction_processing
-https://en.wikipedia.org/wiki/Data_Definition_Language
+https://en.wikipedia.org/wiki/Data_definition_language
-https://en.wikipedia.org/wiki/ORDBMS
+https://en.wikipedia.org/wiki/Object%E2%80%93relational_database
-https://en.wikipedia.org/wiki/GMT
<https://en.wikipedia.org/wiki/Object%E2%80%93relational_database-https://en.wikipedia.org/wiki/GMT>
+https://en.wikipedia.org/wiki/Greenwich_Mean_Time
-https://en.wikipedia.org/wiki/Relational_database_management_system
+https://en.wikipedia.org/wiki/Relational_database#RDBMS
-https://en.wikipedia.org/wiki/Olap
-https://en.wikipedia.org/wiki/Issn
+https://en.wikipedia.org/wiki/Online_analytical_processing
+https://en.wikipedia.org/wiki/ISSN
-https://en.wikipedia.org/wiki/System_V
+https://en.wikipedia.org/wiki/UNIX_System_V
-https://en.wikipedia.org/wiki/Visual_C++
+https://en.wikipedia.org/wiki/Microsoft_Visual_C%2B%2B
-https://en.wikipedia.org/wiki/SGML
+https://en.wikipedia.org/wiki/Standard_Generalized_Markup_Language
-https://en.wikipedia.org/wiki/Ascii
<https://en.wikipedia.org/wiki/Standard_Generalized_Markup_Language-https://en.wikipedia.org/wiki/Ascii>
+https://en.wikipedia.org/wiki/ASCII
-https://en.wikipedia.org/wiki/Dbms
+https://en.wikipedia.org/wiki/Database#Database_management_system
-https://en.wikipedia.org/wiki/Git_(software)
<https://en.wikipedia.org/wiki/Database#Database_management_system-https://en.wikipedia.org/wiki/Git_(software)>
+https://en.wikipedia.org/wiki/Git
-https://en.wikipedia.org/wiki/Utf8
+https://en.wikipedia.org/wiki/UTF-8
-https://en.wikipedia.org/wiki/Secure_Sockets_Layer
+
https://en.wikipedia.org/wiki/Transport_Layer_Security#SSL_1.0,_2.0,_and_3.0

Below is the script I used to find them,
which also reports some additional false positives:

Given this I'd be OK with committing as-is in the name of matching existing
project style. Then bringing up this inconsistency as a separate concern
to be bulk fixed as part of implementing a new policy on what to check for
and conform to when establishing acronyms in our documentation.

Otherwise the author (you) should make the change here - the committer
wouldn't be expected to know to do that from the discussion.

David J.

On Wed, Jun 26, 2024 at 07:58:55AM -0700, David G. Johnston wrote:

On Wed, Jun 26, 2024 at 7:52 AM Joel Jacobson <joel@compiler.org> wrote:

Want me to fix that or will the committer handle that?

I found some more similar cases in acronyms.sgml.

Given this I'd be OK with committing as-is in the name of matching existing
project style. Then bringing up this inconsistency as a separate concern
to be bulk fixed as part of implementing a new policy on what to check for
and conform to when establishing acronyms in our documentation.

Otherwise the author (you) should make the change here - the committer
wouldn't be expected to know to do that from the discussion.

If I was writing these patches, I'd create a separate 0001 patch to fix the
existing problems, then 0002 would be just the new stuff (without the
inconsistency). But that's just what I'd do; there's no problem with doing
it the other way around.

--
nathan

On Wed, Jun 26, 2024 at 8:47 AM Nathan Bossart <nathandbossart@gmail.com>
wrote:

On Wed, Jun 26, 2024 at 07:58:55AM -0700, David G. Johnston wrote:

On Wed, Jun 26, 2024 at 7:52 AM Joel Jacobson <joel@compiler.org> wrote:

Want me to fix that or will the committer handle that?

I found some more similar cases in acronyms.sgml.

Given this I'd be OK with committing as-is in the name of matching

existing

project style. Then bringing up this inconsistency as a separate concern
to be bulk fixed as part of implementing a new policy on what to check

for

and conform to when establishing acronyms in our documentation.

Otherwise the author (you) should make the change here - the committer
wouldn't be expected to know to do that from the discussion.

If I was writing these patches, I'd create a separate 0001 patch to fix the
existing problems, then 0002 would be just the new stuff (without the
inconsistency). But that's just what I'd do; there's no problem with doing
it the other way around.

Agreed, if Joel wants to write both. But as the broader fix shouldn't
block adding a new acronym, it doesn't make sense to insist on this
approach. Consistency makes sense though doing it the expected way would
be OK as well. Either way, assuming the future patch materializes and gets
committed the end state is the same, and the path to it doesn't really
matter.

David J.

On Wed, Jun 26, 2024, at 18:54, David G. Johnston wrote:

On Wed, Jun 26, 2024 at 8:47 AM Nathan Bossart <nathandbossart@gmail.com> wrote:

On Wed, Jun 26, 2024 at 07:58:55AM -0700, David G. Johnston wrote:

On Wed, Jun 26, 2024 at 7:52 AM Joel Jacobson <joel@compiler.org> wrote:

Want me to fix that or will the committer handle that?

I found some more similar cases in acronyms.sgml.

Given this I'd be OK with committing as-is in the name of matching existing
project style. Then bringing up this inconsistency as a separate concern
to be bulk fixed as part of implementing a new policy on what to check for
and conform to when establishing acronyms in our documentation.

Otherwise the author (you) should make the change here - the committer
wouldn't be expected to know to do that from the discussion.

OK, I've made the change, new patch attached.

If I was writing these patches, I'd create a separate 0001 patch to fix the
existing problems, then 0002 would be just the new stuff (without the
inconsistency). But that's just what I'd do; there's no problem with doing
it the other way around.

Agreed, if Joel wants to write both. But as the broader fix shouldn't
block adding a new acronym, it doesn't make sense to insist on this
approach. Consistency makes sense though doing it the expected way
would be OK as well. Either way, assuming the future patch
materializes and gets committed the end state is the same, and the path
to it doesn't really matter.

I'll start a new separate thread about fixing the other non-canonical URLs.

/Joel