Обсуждение: Idea Feedback: psql \h misses -> Offers Links?
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
Example:
\h current_setting
No help available for "current_setting".
Try \h with no arguments to see available help.
No help available for "current_setting".
Try \h with no arguments to see available help.
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&search={token}&go=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.
No help available for "current_setting".
Try \h with no arguments to see available help.
This Latter feature, I would consider applying to even successful searches? [Based on Feedback here]
Thoughts?
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&q=current_setting> 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&q=current_setting
> <https://www.postgresql.org/search/?u=%2Fdocs%2F16%2F&q=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?
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&q=current_setting >> > <https://www.postgresql.org/search/?u=%2Fdocs%2F16%2F&q=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
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&q=current_setting <https://www.postgresql.org/search/?u=%2Fdocs%2F16%2F&q=current_setting> > > > <https://www.postgresql.org/search/?u=%2Fdocs%2F16%2F&q=current_setting <https://www.postgresql.org/search/?u=%2Fdocs%2F16%2F&q=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.
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 toExample:\h current_settingNo 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.
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&search={token}&go=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.
> 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
Thanks!
Best regards, Andrey Borodin.
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 thefirst result is not the one you are looking for. (You are expecting thefunction or parameter description but other page is on the top because it ismore 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&search={token}&go=Go'That's a different idea. Are you proposing to provide URLs if this psqlvariable is set and it doesn't find an entry (say \h foo)? I'm not sure if itis 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 GUCsusing SGML files. We already did it for SQL commands. Another broader idea isto build an inverted index similar to what Index [1] provides. The main problemwith this approach is to create a dependency between documentation build andpsql. Maybe there is a reasonable way to obtain the links for each term.
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.
Thanks for the feedback.