Re: Idea Feedback: psql \h misses -> Offers Links?

[Kirk Wolak]

On Fri, Apr 19, 2024 at 10:14 AM Euler Taveira  wrote:

> On Wed, Apr 17, 2024, at 2:47 PM, Kirk Wolak wrote:
>
> ...
>
> This is Question 1: Do others see the potential value here?
>
>
> Yes. However, I expect an exact and direct answer. There will be cases
> that the
> first result is not the one you are looking for. (You are expecting the
> function or parameter description but other page is on the top because it
> is
> more relevant.) The referred URL does not point you to the direct link.
> Instead, you have to click again to be able to check the content.
>

Again, this does get to the point that the current search feature at
postgresql.org could be better.  I would like to see that improved as
well...


> Question 2: What if we allowed the users to set some extra link Templates
> using \pset??
>
> \pset help_assist_link_1 =  https://www.google.com/search?q={token}'
> \pset help_assist_link_2 = '
> https://wiki.postgresql.org/index.php?title=Special%3ASearch={token}=Go
> 
> '
>
>
> That's a different idea. Are you proposing to provide URLs if this psql
> variable is set and it doesn't find an entry (say \h foo)? I'm not sure if
> it
> is a good idea to allow third-party URLs (even if it is configurable).
>

If you want to check the patch Andrey published.  We basically set the
default value to the set variable, and then allowed the user to override
that value with multiple pipe (|) separated URLs.  It does BEG the question
if this is cool for hackers.  Personally, I like the option as there are
probably a few resources worth checking against.  But if someone doesn't
change the default, they get a good enough answer.


> IMO we should expand \h to list documentation references for functions and
> GUCs
> using SGML files. We already did it for SQL commands. Another broader idea
> is
> to build an inverted index similar to what Index [1] provides. The main
> problem
> with this approach is to create a dependency between documentation build
> and
> psql. Maybe there is a reasonable way to obtain the links for each term.
>
>
> [1] https://www.postgresql.org/docs/current/bookindex.html
>

I don't want to add more dependencies into psql to the documentation for a
ton of stuff.  To me, if we had a better search page on the website for
finding things, it would be great.  I have been resigned to just googling
"postgresql " because google does a better job searching
postgresql.org than the postgresql.org site does (even when it is a known
indexed item like a function name).

Thanks for the feedback.

Re: Idea Feedback: psql \h misses -> Offers Links?

[Pavel Stehule]

čt 2. 5. 2024 v 19:50 odesílatel Andrey M. Borodin 
napsal:

>
>
> > On 17 Apr 2024, at 22:47, Kirk Wolak  wrote:
> >
> > Thoughts?
>
> Today we had a hacking session with Nik and Kirk. We produced a patch to
> assess how these links might look like.
>
> Also we needed a url_encode() and found none in a codebase. It would be
> nice to have this as an SQL-callable function.
>

+1

it was requested more times

Pavel


> Thanks!
>
>
> Best regards, Andrey Borodin.
>
>

Re: Idea Feedback: psql \h misses -> Offers Links?

[Andrey M. Borodin]

> On 17 Apr 2024, at 22:47, Kirk Wolak  wrote:
> 
> Thoughts?

Today we had a hacking session with Nik and Kirk. We produced a patch to assess 
how these links might look like.

Also we needed a url_encode() and found none in a codebase. It would be nice to 
have this as an SQL-callable function.

Thanks!


Best regards, Andrey Borodin.



v1-0001-Add-URLs-to-h-in-psql-when-there-is-no-match.patch
Description: Binary data

Re: Idea Feedback: psql \h misses -> Offers Links?

[Euler Taveira]

On Wed, Apr 17, 2024, at 2:47 PM, Kirk Wolak wrote:
>   I often use the ctrl-click on the link after getting help in psql.  A great 
> feature.
> 
> Challenge, when there is no help, you don't get any link.
> 
>   My thought process is to add a default response that would take them to
> https://www.postgresql.org/search/?u=%2Fdocs%2F16%2F={TOKEN} 
> 
> 
> *Example:*
> \h current_setting
> No help available for "current_setting".
> Try \h with no arguments to see available help.

That's because current_setting is a function. Help says:

postgres=# \?
.
.
.
Help
  \? [commands]  show help on backslash commands
  \? options show help on psql command-line options
  \? variables   show help on special variables
  \h [NAME]  help on syntax of SQL commands, * for all commands

It is just for SQL commands.

> https://www.postgresql.org/search/?u=%2Fdocs%2F16%2F=current_setting
> 
>   To me, this is a huge step in helping me get to the docs.
> 
> This is Question 1: Do others see the potential value here?

Yes. However, I expect an exact and direct answer. There will be cases that the
first result is not the one you are looking for. (You are expecting the
function or parameter description but other page is on the top because it is
more relevant.) The referred URL does not point you to the direct link.
Instead, you have to click again to be able to check the content.

> Question 2: What if we allowed the users to set some extra link Templates 
> using \pset??
> 
> \pset help_assist_link_1 =  https://www.google.com/search?q={token} 
> '
> \pset help_assist_link_2 = 
> 'https://wiki.postgresql.org/index.php?title=Special%3ASearch={token}=Go
>  
> '

That's a different idea. Are you proposing to provide URLs if this psql
variable is set and it doesn't find an entry (say \h foo)? I'm not sure if it
is a good idea to allow third-party URLs (even if it is configurable).

IMO we should expand \h to list documentation references for functions and GUCs
using SGML files. We already did it for SQL commands. Another broader idea is
to build an inverted index similar to what Index [1] provides. The main problem
with this approach is to create a dependency between documentation build and
psql. Maybe there is a reasonable way to obtain the links for each term.


[1] https://www.postgresql.org/docs/current/bookindex.html


--
Euler Taveira
EDB   https://www.enterprisedb.com/

Re: Idea Feedback: psql \h misses -> Offers Links?

[Peter Eisentraut]

On 18.04.24 23:29, Kirk Wolak wrote:
On Thu, Apr 18, 2024 at 2:37 PM Peter Eisentraut > wrote:


On 17.04.24 19:47, Kirk Wolak wrote:
 > *Example:*
 > \h current_setting
 > No help available for "current_setting".
 > Try \h with no arguments to see available help.
 >
 >
https://www.postgresql.org/search/?u=%2Fdocs%2F16%2F=current_setting 

 >
>

One problem is that this search URL does not actually produce any
useful
information about current_setting.

I see what you mean, but doesn't that imply our web search feature is 
weak?  That's the full name of an existing function, and it's in the 
index. But it cannot be found if searched from the website?


Maybe it's weak, or maybe we are using it wrong, I don't know.

\h has always been (a) local help, and (b) help specifically about SQL 
commands.  If we are going to vastly expand the scope, we need to think 
it through more thoroughly.  I could see some kind of \onlinehelp 
command, or maybe even redesigning \h altogether.


Also, as you say, the function is in the documentation index, so there 
should be a deterministic way to go directly to exactly the target 
destination.  Maybe the full-text search functionality of the web site 
is the wrong interface for that.

Re: Idea Feedback: psql \h misses -> Offers Links?

[Dagfinn Ilmari Mannsåker]

Kirk Wolak  writes:

> On Thu, Apr 18, 2024 at 2:37 PM Peter Eisentraut 
> wrote:
>
>> On 17.04.24 19:47, Kirk Wolak wrote:
>> > *Example:*
>> > \h current_setting
>> > No help available for "current_setting".
>> > Try \h with no arguments to see available help.
>> >
>> > https://www.postgresql.org/search/?u=%2Fdocs%2F16%2F=current_setting
>> > 
>>
>> One problem is that this search URL does not actually produce any useful
>> information about current_setting.
>
> I see what you mean, but doesn't that imply our web search feature is
> weak?  That's the full name of an existing function, and it's in the index.
> But it cannot be found if searched from the website?

While I do think we could do a better job of providing links directly to
the documentation of functions and config parameters, I wouldn't say
that the search result is _completely_ useless in this case.  The first
hit is https://www.postgresql.org/docs/16/functions-admin.html, which is
where current_setting() is documented (it's even the first function on
that page, but that's just luck in this case).

- ilmari

Re: Idea Feedback: psql \h misses -> Offers Links?

[Kirk Wolak]

On Thu, Apr 18, 2024 at 2:37 PM Peter Eisentraut 
wrote:

> On 17.04.24 19:47, Kirk Wolak wrote:
> > *Example:*
> > \h current_setting
> > No help available for "current_setting".
> > Try \h with no arguments to see available help.
> >
> > https://www.postgresql.org/search/?u=%2Fdocs%2F16%2F=current_setting
> > 
>
> One problem is that this search URL does not actually produce any useful
> information about current_setting.
>
> I see what you mean, but doesn't that imply our web search feature is
weak?  That's the full name of an existing function, and it's in the index.
But it cannot be found if searched from the website?

Re: Idea Feedback: psql \h misses -> Offers Links?

[Peter Eisentraut]

On 17.04.24 19:47, Kirk Wolak wrote:

*Example:*
\h current_setting
No help available for "current_setting".
Try \h with no arguments to see available help.

https://www.postgresql.org/search/?u=%2Fdocs%2F16%2F=current_setting 



One problem is that this search URL does not actually produce any useful 
information about current_setting.

Idea Feedback: psql \h misses -> Offers Links?

[Kirk Wolak]

  Hackers,
  I often use the ctrl-click on the link after getting help in psql.  A
great feature.

Challenge, when there is no help, you don't get any link.

  My thought process is to add a default response that would take them to
https://www.postgresql.org/search/?u=%2Fdocs%2F16%2F={TOKEN}


*Example:*
\h current_setting
No help available for "current_setting".
Try \h with no arguments to see available help.

https://www.postgresql.org/search/?u=%2Fdocs%2F16%2F=current_setting

  To me, this is a huge step in helping me get to the docs.

This is Question 1: Do others see the potential value here?

Question 2: What if we allowed the users to set some extra link Templates
using \pset??

\pset help_assist_link_1 =  https://www.google.com/search?q={token}'
\pset help_assist_link_2 = '
https://wiki.postgresql.org/index.php?title=Special%3ASearch={token}=Go

'

Such that the output, this time would be:
*Example:*
\h current_setting
No help available for "current_setting".
Try \h with no arguments to see available help.

https://www.postgresql.org/search/?u=%2Fdocs%2F16%2F=current_setting

https://www.google.com/search?q=current_setting
https://wiki.postgresql.org/index.php?title=Special%3ASearch=current_setting=Go

This Latter feature, I would consider applying to even successful searches?
[Based on Feedback here]

Thoughts?