Thread: [PATCH] Add ACL (Access Control List) acronym

Hello hackers,

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.

[1] https://postgr.es/m/Zniz1n7qa3_i4iac%40paquier.xyz

/Joel

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">Access Control List, i.e. privileges
list</ulink>

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

-- 
nathan

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 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 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 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://[^"]*' 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 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 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

On Thu, Jun 27, 2024, at 10:42, Joel Jacobson wrote:
> I'll start a new separate thread about fixing the other non-canonical URLs.

Here is the separate thread to fix the docs to use canonical links:
https://postgr.es/m/8ccc96c7-0515-491b-be98-cfacdaeda815@app.fastmail.com

On Wed, Jun 26, 2024 at 09:30:27AM +0900, Michael Paquier wrote:
> Fine by me as well.  I guess I'll just apply that once v18 opens up.

And done with 00d819d46a6f.
--
Michael