Re: client auth docs seem to have devolved

While following an old link to
/docs/10/auth-methods.html

I see a list of links to authentication methods. However:

When I hit the current version
/docs/current/auth-methods.html

There are absolutely no links...

Dave Cramer

On Tue, Dec 17, 2019 at 12:43 PM Dave Cramer <davecramer(at)gmail(dot)com> wrote:

> While following an old link to
> /docs/10/auth-methods.html
>
> I see a list of links to authentication methods. However:
>
> When I hit the current version
> /docs/current/auth-methods.html
>
> There are absolutely no links...
>
>
That's because the structure of the docs changed. You need to hit "up",
which will take you to
/docs/current/client-authentication.html, which
now has the list of links. Note how the different methods used to be
20.3.x, and are now directly listed as 20.y.

I'm unsure if that was intentional in the upstream docs, but that's what
makes the website behave like it does.

--
Magnus Hagander
Me: https://www.hagander.net/ <http://www.hagander.net/>
Work: https://www.redpill-linpro.com/ <http://www.redpill-linpro.com/>

On Tue, 17 Dec 2019 at 06:53, Magnus Hagander <magnus(at)hagander(dot)net> wrote:

> On Tue, Dec 17, 2019 at 12:43 PM Dave Cramer <davecramer(at)gmail(dot)com> wrote:
>
>> While following an old link to
>> /docs/10/auth-methods.html
>>
>> I see a list of links to authentication methods. However:
>>
>> When I hit the current version
>> /docs/current/auth-methods.html
>>
>> There are absolutely no links...
>>
>>
> That's because the structure of the docs changed. You need to hit "up",
> which will take you to
> /docs/current/client-authentication.html, which
> now has the list of links. Note how the different methods used to be
> 20.3.x, and are now directly listed as 20.y.
>
> I'm unsure if that was intentional in the upstream docs, but that's what
> makes the website behave like it does.
>

Fair enough but

20.3. Authentication Methods
The following sections describe the authentication methods in more detail.

certainly is misleading.

Thanks,

Dave

>

On Tue, Dec 17, 2019 at 1:02 PM Dave Cramer <davecramer(at)gmail(dot)com> wrote:

> On Tue, 17 Dec 2019 at 06:53, Magnus Hagander <magnus(at)hagander(dot)net> wrote:
>
>> On Tue, Dec 17, 2019 at 12:43 PM Dave Cramer <davecramer(at)gmail(dot)com>
>> wrote:
>>
>>> While following an old link to
>>> /docs/10/auth-methods.html
>>>
>>> I see a list of links to authentication methods. However:
>>>
>>> When I hit the current version
>>> /docs/current/auth-methods.html
>>>
>>> There are absolutely no links...
>>>
>>>
>> That's because the structure of the docs changed. You need to hit "up",
>> which will take you to
>> /docs/current/client-authentication.html,
>> which now has the list of links. Note how the different methods used to be
>> 20.3.x, and are now directly listed as 20.y.
>>
>> I'm unsure if that was intentional in the upstream docs, but that's what
>> makes the website behave like it does.
>>
>
> Fair enough but
>
> 20.3. Authentication Methods
> The following sections describe the authentication methods in more detail.
>
> certainly is misleading.
>
>
This was changed by Peter in
commit 56811e57323faa453947eb82f007e323a952e1a1 along with the
restructuring. It used to say "the following subsections". So techically I
think that change is correct, but that doesn't necessarily make it helpful.

But based on how it actually renders, since that section doesn't contain
any actual useful info, we should perhaps just remove section 20.3
completely. Peter, thoughts?

--
Magnus Hagander
Me: https://www.hagander.net/ <http://www.hagander.net/>
Work: https://www.redpill-linpro.com/ <http://www.redpill-linpro.com/>

Magnus Hagander <magnus(at)hagander(dot)net> writes:
> This was changed by Peter in
> commit 56811e57323faa453947eb82f007e323a952e1a1 along with the
> restructuring. It used to say "the following subsections". So techically I
> think that change is correct, but that doesn't necessarily make it helpful.

> But based on how it actually renders, since that section doesn't contain
> any actual useful info, we should perhaps just remove section 20.3
> completely. Peter, thoughts?

Then, URLs pointing to that page (such as Dave evidently has bookmarked)
would break entirely, which doesn't seem like an improvement.

I suggest changing the sect1's contents to be a list of available auth
methods, linked to their subsections. That would provide approximately
the same quality-of-use as the subsection TOC that used to be there.

regards, tom lane

> Then, URLs pointing to that page (such as Dave evidently has bookmarked)
> would break entirely, which doesn't seem like an improvement.
>

it was linked to in a bug report.

Dave Cramer

On Tue, Dec 17, 2019 at 5:01 PM Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:

> Magnus Hagander <magnus(at)hagander(dot)net> writes:
> > This was changed by Peter in
> > commit 56811e57323faa453947eb82f007e323a952e1a1 along with the
> > restructuring. It used to say "the following subsections". So techically
> I
> > think that change is correct, but that doesn't necessarily make it
> helpful.
>
> > But based on how it actually renders, since that section doesn't contain
> > any actual useful info, we should perhaps just remove section 20.3
> > completely. Peter, thoughts?
>
> Then, URLs pointing to that page (such as Dave evidently has bookmarked)
> would break entirely, which doesn't seem like an improvement.
>

Ugh, that's a good point of course. Didn't think of that.

I suggest changing the sect1's contents to be a list of available auth
> methods, linked to their subsections. That would provide approximately
> the same quality-of-use as the subsection TOC that used to be there.
>

Yeah, that sounds better. Is there some docbook magic that can do that for
us?

--
Magnus Hagander
Me: https://www.hagander.net/ <http://www.hagander.net/>
Work: https://www.redpill-linpro.com/ <http://www.redpill-linpro.com/>

Magnus Hagander <magnus(at)hagander(dot)net> writes:
> On Tue, Dec 17, 2019 at 5:01 PM Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:
>> I suggest changing the sect1's contents to be a list of available auth
>> methods, linked to their subsections. That would provide approximately
>> the same quality-of-use as the subsection TOC that used to be there.

> Yeah, that sounds better. Is there some docbook magic that can do that for
> us?

I was just intending to do it the hard way, since even if such magic
exists, it'd probably only regurgitate the section titles. It seems
more useful to allow for some descriptive text along with that.
(Not a lot, but maybe a full sentence for each one.)

regards, tom lane

I wrote:
> Magnus Hagander <magnus(at)hagander(dot)net> writes:
>> This was changed by Peter in
>> commit 56811e57323faa453947eb82f007e323a952e1a1 along with the
>> restructuring. It used to say "the following subsections". So techically I
>> think that change is correct, but that doesn't necessarily make it helpful.
>> But based on how it actually renders, since that section doesn't contain
>> any actual useful info, we should perhaps just remove section 20.3
>> completely. Peter, thoughts?

> Then, URLs pointing to that page (such as Dave evidently has bookmarked)
> would break entirely, which doesn't seem like an improvement.

Also, our docs' own internal links to that section would break --- there
are built-in assumptions that there's one pointable-to place that explains
all the auth methods.

> I suggest changing the sect1's contents to be a list of available auth
> methods, linked to their subsections. That would provide approximately
> the same quality-of-use as the subsection TOC that used to be there.

Concretely, I propose the attached. Anybody want to editorialize on
my short descriptions of the auth methods?

regards, tom lane

I wrote:
> Concretely, I propose the attached. Anybody want to editorialize on
> my short descriptions of the auth methods?

Pushed after a bit more fiddling with the wording.

regards, tom lane

On 2019-Dec-19, Tom Lane wrote:

> I wrote:
> > Concretely, I propose the attached. Anybody want to editorialize on
> > my short descriptions of the auth methods?
>
> Pushed after a bit more fiddling with the wording.

Looks good, thanks.

--
Álvaro Herrera https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services