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

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&q=current_setting
<https://www.postgresql.org/search/?u=%2Fdocs%2F16%2F&amp;q=current_setting&gt;

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

On Thu, Apr 18, 2024 at 2:37 PM Peter Eisentraut <peter@eisentraut.org>
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&amp;q=current_setting
<https://www.postgresql.org/search/?u=%2Fdocs%2F16%2F&amp;q=current_setting&gt;

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?

Kirk Wolak <wolakk@gmail.com> writes:

On Thu, Apr 18, 2024 at 2:37 PM Peter Eisentraut <peter@eisentraut.org>
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&amp;q=current_setting
<https://www.postgresql.org/search/?u=%2Fdocs%2F16%2F&amp;q=current_setting&gt;

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

On 18.04.24 23:29, Kirk Wolak wrote:

On Thu, Apr 18, 2024 at 2:37 PM Peter Eisentraut <peter@eisentraut.org
<mailto:peter@eisentraut.org>> 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&amp;q=current_setting <https://www.postgresql.org/search/?u=%2Fdocs%2F16%2F&amp;q=current_setting&gt;

<https://www.postgresql.org/search/?u=%2Fdocs%2F16%2F&amp;q=current_setting <https://www.postgresql.org/search/?u=%2Fdocs%2F16%2F&amp;q=current_setting&gt;&gt;

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.

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&amp;q={TOKEN} <https://www.postgresql.org/search/?u=%2Fdocs%2F16%2F&amp;q=%7BTOKEN%7D&gt;

*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&amp;q=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} <https://www.google.com/search?q=%7Btoken%7D&gt;&#39;
\pset help_assist_link_2 = 'https://wiki.postgresql.org/index.php?title=Special%3ASearch&amp;search={token}&amp;go=Go <https://wiki.postgresql.org/index.php?title=Special%3ASearch&amp;search=%7Btoken%7D&amp;go=Go&gt;&#39;

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]https://www.postgresql.org/docs/current/bookindex.html 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/

On 17 Apr 2024, at 22:47, Kirk Wolak <wolakk@gmail.com> 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.

čt 2. 5. 2024 v 19:50 odesílatel Andrey M. Borodin <x4mmm@yandex-team.ru>
napsal:

On 17 Apr 2024, at 22:47, Kirk Wolak <wolakk@gmail.com> 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

On Fri, Apr 19, 2024 at 10:14 AM Euler Taveira <euler@eulerto.com> 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}&#39;
\pset help_assist_link_2 = '
https://wiki.postgresql.org/index.php?title=Special%3ASearch&amp;search={token}&amp;go=Go
<https://wiki.postgresql.org/index.php?title=Special%3ASearch&amp;search=%7Btoken%7D&amp;go=Go&gt;
'

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 <topic>" 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.