Thread: [HACKERS] psql: new help related to variables are not too readable

[HACKERS] psql: new help related to variables are not too readable

From
Pavel Stehule
Date:
Hi

Now the output looks like:

  AUTOCOMMIT
    if set, successful SQL commands are automatically committed
  COMP_KEYWORD_CASE
    determines the case used to complete SQL key words
    [lower, upper, preserve-lower, preserve-upper]
  DBNAME
    the currently connected database name
  ECHO
    controls what input is written to standard output
    [all, errors, none, queries]
  ECHO_HIDDEN
    if set, display internal queries executed by backslash commands;
    if set to "noexec", just show them without execution
  ENCODING
    current client character set encoding
  FETCH_COUNT
    the number of result rows to fetch and display at a time (0 = unlimited)
  HISTCONTROL
    controls command history [ignorespace, ignoredups, ignoreboth]
  HISTFILE
    file name used to store the command history
  HISTSIZE
    max number of commands to store in the command history
  HOST

What do you think about using new line between entries in this format?

  AUTOCOMMIT
    if set, successful SQL commands are automatically committed

  COMP_KEYWORD_CASE
    determines the case used to complete SQL key words
    [lower, upper, preserve-lower, preserve-upper]

  DBNAME
    the currently connected database name

  ECHO
    controls what input is written to standard output
    [all, errors, none, queries]

  ECHO_HIDDEN
    if set, display internal queries executed by backslash commands;
    if set to "noexec", just show them without execution

  ENCODING
    current client character set encoding

  FETCH_COUNT
    the number of result rows to fetch and display at a time (0 = unlimited)

  HISTCONTROL
    controls command history [ignorespace, ignoredups, ignoreboth]

  HISTFILE
    file name used to store the command history

  HISTSIZE
    max number of commands to store in the command history

Regards

Pavel

Re: [HACKERS] psql: new help related to variables are not tooreadable

From
Erik Rijkers
Date:
On 2017-09-08 06:09, Pavel Stehule wrote:
> Hi
> 
> Now the output looks like:
> 
>   AUTOCOMMIT
>     if set, successful SQL commands are automatically committed
>   COMP_KEYWORD_CASE
>     determines the case used to complete SQL key words
>     [lower, upper, preserve-lower, preserve-upper]
>   DBNAME
>     the currently connected database name
[...]
> What do you think about using new line between entries in this format?
> 
>   AUTOCOMMIT
>     if set, successful SQL commands are automatically committed
> 
>   COMP_KEYWORD_CASE
>     determines the case used to complete SQL key words
>     [lower, upper, preserve-lower, preserve-upper]
> 
>   DBNAME
>     the currently connected database name
> 

I dislike it, it takes more screen space and leads to unneccessary 
scroll-need.

The 9.6.5 formatting is/was:
  AUTOCOMMIT         if set, successful SQL commands are automatically 
committed  COMP_KEYWORD_CASE  determines the case used to complete SQL key words                     [lower, upper,
preserve-lower,preserve-upper]  DBNAME             the currently connected database name
 
[...]  PGPASSWORD         connection password (not recommended)  PGPASSFILE         password file name  PSQL_EDITOR,
EDITOR,VISUAL                     editor used by the \e, \ef, and \ev commands  PSQL_EDITOR_LINENUMBER_ARG
      how to specify a line number when invoking the 
 
editor  PSQL_HISTORY       alternative location for the command history file

I would prefer to revert to that more compact 9.6-formatting.


Erik Rijkers


-- 
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

Re: [HACKERS] psql: new help related to variables are not too readable

From
Pavel Stehule
Date:


2017-09-08 6:36 GMT+02:00 Erik Rijkers <er@xs4all.nl>:
On 2017-09-08 06:09, Pavel Stehule wrote:
Hi

Now the output looks like:

  AUTOCOMMIT
    if set, successful SQL commands are automatically committed
  COMP_KEYWORD_CASE
    determines the case used to complete SQL key words
    [lower, upper, preserve-lower, preserve-upper]
  DBNAME
    the currently connected database name
[...]
What do you think about using new line between entries in this format?

  AUTOCOMMIT
    if set, successful SQL commands are automatically committed

  COMP_KEYWORD_CASE
    determines the case used to complete SQL key words
    [lower, upper, preserve-lower, preserve-upper]

  DBNAME
    the currently connected database name


I dislike it, it takes more screen space and leads to unneccessary scroll-need.

The 9.6.5 formatting is/was:

  AUTOCOMMIT         if set, successful SQL commands are automatically committed
  COMP_KEYWORD_CASE  determines the case used to complete SQL key words
                     [lower, upper, preserve-lower, preserve-upper]
  DBNAME             the currently connected database name
[...]
  PGPASSWORD         connection password (not recommended)
  PGPASSFILE         password file name
  PSQL_EDITOR, EDITOR, VISUAL
                     editor used by the \e, \ef, and \ev commands
  PSQL_EDITOR_LINENUMBER_ARG
                     how to specify a line number when invoking the editor
  PSQL_HISTORY       alternative location for the command history file

I would prefer to revert to that more compact 9.6-formatting.

There was a problem with line width .. its hard to respect 80 chars
 



Erik Rijkers

Re: [HACKERS] psql: new help related to variables are not tooreadable

From
Fabien COELHO
Date:
Hello,

>>   PSQL_HISTORY       alternative location for the command history file
>>
>> I would prefer to revert to that more compact 9.6-formatting.
>
> There was a problem with line width .. its hard to respect 80 chars

Yes.

Scrolling in two dimensions because it does not fit either way is not too 
practical, so the idea was the it should at least fit a reasonable 
terminal in the horizontal dimension, the vertical one having been 
unfittable anyway for a long time.

Once you want to do strict 80 columns, a lot of/most descriptions do not 
fit and need to be split somehow on two lines, one way or another. It 
seemed that
  XXXXXXX      xxxx xxx xx xxx xxx xxxx

Is a good way to do that systematically and with giving more space and 
chance for a description to fit in its line. ISTM that it was already done 
like for environment variables, so it is also for homogeneity.

It also simplify work for translators that can just follow the same 
formatting and know what to do if a one line English explanation does
not fit once translated.

Finally, as vertical scrolling is mandatory, I would be fine with skipping 
lines with entries for readability, but it is just a matter of taste and I 
expect there should be half a dozen different opinions on the matter of 
formatting.

-- 
Fabien.


-- 
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

Re: [HACKERS] psql: new help related to variables are not tooreadable

From
Tomas Vondra
Date:
Hi,

On 09/08/2017 07:25 AM, Fabien COELHO wrote:
> 
> Hello,
> 
>>>   PSQL_HISTORY       alternative location for the command history file
>>>
>>> I would prefer to revert to that more compact 9.6-formatting.
>>
>> There was a problem with line width .. its hard to respect 80 chars
> 
> Yes.
> 
> Scrolling in two dimensions because it does not fit either way is not
> too practical, so the idea was the it should at least fit a reasonable
> terminal in the horizontal dimension, the vertical one having been
> unfittable anyway for a long time.
> 
> Once you want to do strict 80 columns, a lot of/most descriptions do not
> fit and need to be split somehow on two lines, one way or another. It
> seemed that
> 
>   XXXXXXX
>       xxxx xxx xx xxx xxx xxxx
> 
> Is a good way to do that systematically and with giving more space and
> chance for a description to fit in its line. ISTM that it was already
> done like for environment variables, so it is also for homogeneity.
> 

FWIW I also find the new formatting hard to read, as it does not clearly
separate the items. The old formatting was not ideal either, though.

>
> It also simplify work for translators that can just follow the same
> formatting and know what to do if a one line English explanation does
> not fit once translated.
> 

As someone responsible for a significant part of the Czech translation,
I find this argument somewhat dubious. I don't see how this
 _("XXXX "   "  yyyy")

simplifies the work for translators, compared to this
 _("XXXX yyyy")

The translator has exactly the same context in both cases, and the
struggle to wrap it at 80 characters will be pretty much the same too.

The thing that would make a difference is automatic wrapping, i.e.
split on spaces, then re-build into shorter than 80 characters ...

> Finally, as vertical scrolling is mandatory, I would be fine with
> skipping lines with entries for readability, but it is just a matter of
> taste and I expect there should be half a dozen different opinions on
> the matter of formatting.
> 

FWIW, +1 to extra lines from me - I find it way more readable, as it
clearly separates the items. You're right this is also a matter of taste
to some degree, so I understand Erik's point about vertical scrolling.

regards

-- 
Tomas Vondra                  http://www.2ndQuadrant.com
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services


-- 
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

Re: [HACKERS] psql: new help related to variables are not too readable

From
Tom Lane
Date:
Tomas Vondra <tomas.vondra@2ndquadrant.com> writes:
> The translator has exactly the same context in both cases, and the
> struggle to wrap it at 80 characters will be pretty much the same too.

Really?  With the old way, you had something under 60 characters to
work in, now it's nearly 80.  I don't buy that that's not a significant
difference.  It's also much less ugly if you decide you need one more
line than the English version uses.
        regards, tom lane


-- 
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

Re: [HACKERS] psql: new help related to variables are not tooreadable

From
Alvaro Herrera
Date:
Tomas Vondra wrote:

> > Finally, as vertical scrolling is mandatory, I would be fine with
> > skipping lines with entries for readability, but it is just a matter of
> > taste and I expect there should be half a dozen different opinions on
> > the matter of formatting.
> 
> FWIW, +1 to extra lines from me - I find it way more readable, as it
> clearly separates the items.

+1

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


-- 
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

Re: [HACKERS] psql: new help related to variables are not too readable

From
Pavel Stehule
Date:
Hi

2017-09-09 1:24 GMT+02:00 Tom Lane <tgl@sss.pgh.pa.us>:
Tomas Vondra <tomas.vondra@2ndquadrant.com> writes:
> The translator has exactly the same context in both cases, and the
> struggle to wrap it at 80 characters will be pretty much the same too.

Really?  With the old way, you had something under 60 characters to
work in, now it's nearly 80.  I don't buy that that's not a significant
difference.  It's also much less ugly if you decide you need one more
line than the English version uses.


here is patch - anybody can check if with this change will be result better or not.

Regards

Pavel
 
                        regards, tom lane

Attachment

Re: [HACKERS] psql: new help related to variables are not tooreadable

From
Tomas Vondra
Date:
On 09/09/2017 01:24 AM, Tom Lane wrote:
> Tomas Vondra <tomas.vondra@2ndquadrant.com> writes:
>> The translator has exactly the same context in both cases, and the
>> struggle to wrap it at 80 characters will be pretty much the same too.
> 
> Really?  With the old way, you had something under 60 characters to
> work in, now it's nearly 80.  I don't buy that that's not a significant
> difference.  It's also much less ugly if you decide you need one more
> line than the English version uses.
> 

That's not what I meant. I've never felt a strong urge to avoid wrapping
at 80 chars when translating strings - simply translate in the most
meaningful way, if it gets longer than 80 chars and can't be easily
shortened, just wrap. If there are 60 or 80 characters does not change
this much - 80 chars may allow more unwrapped strings, of course, but
it's a minor change for the translators. Or at least me, others may
disagree, of course.

What I find way more annoying are strings where it's not clear where to
wrap, because it gets prefixed by something, we insert a value while
formatting the error message, etc. But that's not the case here, as both
 _("XXXX "   "  yyyy")

and
 _("XXXX yyyy")

give you the whole string.


regards

-- 
Tomas Vondra                  http://www.2ndQuadrant.com
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services


-- 
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

Re: [HACKERS] psql: new help related to variables are not too readable

From
"Daniel Verite"
Date:
    Tomas Vondra wrote:

> That's not what I meant. I've never felt a strong urge to avoid wrapping
> at 80 chars when translating strings - simply translate in the most
> meaningful way, if it gets longer than 80 chars and can't be easily
> shortened, just wrap. If there are 60 or 80 characters does not change
> this much - 80 chars may allow more unwrapped strings, of course, but
> it's a minor change for the translators. Or at least me, others may
> disagree, of course.

The difficulty varies across languages since some are more compact
than others, and the choice of wrapping or not is not
consistent across translations.

As an example, in the previous version, the first variable comes
out as:

en AUTOCOMMIT         if set, successful SQL commands are automatically
committed

de AUTOCOMMIT         wenn gesetzt werden alle erfolgreichen SQL-Befehle         automatisch committet
es AUTOCOMMIT         si está definida, órdenes SQL exitosas se comprometen         automáticamente
fr AUTOCOMMIT         si activé, les commandes SQL réussies sont
automatiquement validées

he AUTOCOMMIT        אם הופעל, פקודות SQL מחויבות באופן אוטומטי

it AUTOCOMMIT         se impostato, i comandi SQL riusciti sono salvati
automaticamente

ko AUTOCOMMIT         지정 하면 SQL 명령이 성공하면 자동으로 커밋

pl AUTOCOMMIT         gdy ustawiony, polecenia SQL zakończone powodzeniem są
automatycznie zatwierdzone

pt_BR AUTOCOMMIT         se definido, comandos SQL bem sucedidos são
automaticamente efetivados

ru AUTOCOMMIT         если установлен, успешные SQL-команды фиксируются
автоматически

sv AUTOCOMMIT         om satt, efterföljande SQL-kommandon commit:as
automatiskt

zh_CN AUTOCOMMIT         如果被设置,成功的SQL命令将会被自动提交

The original line in english has exactly 80 characters.
When translated in other latin languages, it tends to be a bit
longer.

German and spanish translators have taken the trouble
to break the message into two lines of less than
80 chars with the second one nicely indented, also
aligned in the .po file:

msgid "  AUTOCOMMIT        if set, successful SQL commands are automatically
committed\n"
msgstr ""
"  AUTOCOMMIT          si está definida, órdenes SQL exitosas se
comprometen\n"
"              automáticamente\n"


But other translations are not necessarily done this way, or
at least not consistently. If only for that, having more
characters in the description before screen wrap should help
a bit. In the above example, I think with the new presentation
only the polish version wouldn't fit in 80 chars without
wrapping.


Best regards,
--
Daniel Vérité
PostgreSQL-powered mailer: http://www.manitou-mail.org
Twitter: @DanielVerite


--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

Re: [HACKERS] psql: new help related to variables are not too readable

From
Pavel Stehule
Date:


2017-09-09 1:30 GMT+02:00 Alvaro Herrera <alvherre@alvh.no-ip.org>:
Tomas Vondra wrote:

> > Finally, as vertical scrolling is mandatory, I would be fine with
> > skipping lines with entries for readability, but it is just a matter of
> > taste and I expect there should be half a dozen different opinions on
> > the matter of formatting.
>
> FWIW, +1 to extra lines from me - I find it way more readable, as it
> clearly separates the items.

+1

I'll assign this patch to next commitfest
 

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

Re: [HACKERS] psql: new help related to variables are not tooreadable

From
Fabien COELHO
Date:
>>>> Finally, as vertical scrolling is mandatory, I would be fine with
>>>> skipping lines with entries for readability, but it is just a matter of
>>>> taste and I expect there should be half a dozen different opinions on
>>>> the matter of formatting.
>>>
>>> FWIW, +1 to extra lines from me - I find it way more readable, as it
>>> clearly separates the items.
>>
>> +1

As already said above +1 for me for having more space.

> I'll assign this patch to next commitfest

Probably it needs some rebase after Tom committed result status variables.

As it is a style thing, ISTM that the patch is ready if most people agree
that it is better this way and there is no strong veto against.

-- 
Fabien.


-- 
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

Re: [HACKERS] psql: new help related to variables are not too readable

From
Tom Lane
Date:
Fabien COELHO <coelho@cri.ensmp.fr> writes:
>> I'll assign this patch to next commitfest

> Probably it needs some rebase after Tom committed result status variables.

> As it is a style thing, ISTM that the patch is ready if most people agree
> that it is better this way and there is no strong veto against.

FWIW, I think it's a bad idea.  We already nearly-doubled the vertical
space required for this variable list.  That was a heavy cost --- and we
already got at least one complaint about it --- but it seemed warranted
to avoid having to deal with very constrained variable descriptions.
This proposes to make the vertical space nearly triple what it was in v10.
In a typical-size window that's going to have a pretty severe impact on
how much of the list you can see at once.  And the readability gain is
(at least to my eyes) very marginal.
        regards, tom lane


-- 
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

Re: [HACKERS] psql: new help related to variables are not too readable

From
Pavel Stehule
Date:


2017-09-13 16:11 GMT+02:00 Tom Lane <tgl@sss.pgh.pa.us>:
Fabien COELHO <coelho@cri.ensmp.fr> writes:
>> I'll assign this patch to next commitfest

> Probably it needs some rebase after Tom committed result status variables.

> As it is a style thing, ISTM that the patch is ready if most people agree
> that it is better this way and there is no strong veto against.

FWIW, I think it's a bad idea.  We already nearly-doubled the vertical
space required for this variable list.  That was a heavy cost --- and we
already got at least one complaint about it --- but it seemed warranted
to avoid having to deal with very constrained variable descriptions.
This proposes to make the vertical space nearly triple what it was in v10.
In a typical-size window that's going to have a pretty severe impact on
how much of the list you can see at once.  And the readability gain is
(at least to my eyes) very marginal.

unfortunately - readability is subjective. Now it is really hard to read to me. I understand so text is long enough already, and with lot of empty lines, it will be longer.

because we cannot to use colors or some effects (bold, ..)  I am not feeling to well when I read it.

I proposed it because readability of current design is not too good - but it is not major topic for me - so should not to push this topic too much. Somebody can read it better, some not - it is subjective.

Regards

Pavel

                        regards, tom lane

Re: [HACKERS] psql: new help related to variables are not tooreadable

From
Alvaro Herrera
Date:
Most of the time I suppose you'd search (using the pager's search
function) whatever you're looking for, rather than read the whole
page from top to bottom.

Why is it that we're not opening the pager automatically when this help
is invoked via psql --help=variables?  "\? variables" already does that.

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


-- 
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

Re: [HACKERS] psql: new help related to variables are not too readable

From
Tom Lane
Date:
Alvaro Herrera <alvherre@alvh.no-ip.org> writes:
> Why is it that we're not opening the pager automatically when this help
> is invoked via psql --help=variables?  "\? variables" already does that.

Hm, given that output from a -c option does get paginated (I just
checked), maybe that should happen.
        regards, tom lane


-- 
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

Re: [HACKERS] psql: new help related to variables are not tooreadable

From
Fabien COELHO
Date:
Hello Tom,

>> Probably it needs some rebase after Tom committed result status variables.
>
>> As it is a style thing, ISTM that the patch is ready if most people agree
>> that it is better this way and there is no strong veto against.
>
> FWIW, I think it's a bad idea.  We already nearly-doubled the vertical
> space required for this variable list.  That was a heavy cost --- and we
> already got at least one complaint about it --- but it seemed warranted
> to avoid having to deal with very constrained variable descriptions.
> This proposes to make the vertical space nearly triple what it was in v10.
> In a typical-size window that's going to have a pretty severe impact on
> how much of the list you can see at once.  And the readability gain is
> (at least to my eyes) very marginal.

Ok, you do not like it. As Pavel said, it is subjective. When it is a 
matter of taste, people tend to differ, someone will always complain, one 
way or another, and they are neither right nor wrong.

So, is it a -1 or a veto?

If it is the later, the patch can be marked as "Rejected" and everybody 
will get more time for other things:-)

If it is a not a veto, people can continue to give their opinions. 
Personnally I'm fine with a pager, so vertical spacing is fine. I just do 
not like paging horizontally.

-- 
Fabien.


-- 
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

Re: [HACKERS] psql: new help related to variables are not too readable

From
"David G. Johnston"
Date:
On Wed, Sep 13, 2017 at 12:46 PM, Fabien COELHO <coelho@cri.ensmp.fr> wrote:

Hello Tom,

Probably it needs some rebase after Tom committed result status variables.

As it is a style thing, ISTM that the patch is ready if most people agree
that it is better this way and there is no strong veto against.

FWIW, I think it's a bad idea.  We already nearly-doubled the vertical
space required for this variable list.  That was a heavy cost --- and we
already got at least one complaint about it --- but it seemed warranted
to avoid having to deal with very constrained variable descriptions.
This proposes to make the vertical space nearly triple what it was in v10.
In a typical-size window that's going to have a pretty severe impact on
how much of the list you can see at once.  And the readability gain is
(at least to my eyes) very marginal.

Ok, you do not like it. As Pavel said, it is subjective. When it is a matter of taste, people tend to differ, someone will always complain, one way or another, and they are neither right nor wrong.

So, is it a -1 or a veto?

If it is the later, the patch can be marked as "Rejected" and everybody will get more time for other things:-)

If it is a not a veto, people can continue to give their opinions. Personnally I'm fine with a pager, so vertical spacing is fine. I just do not like paging horizontally.

​-1​

​I don't fully by the "it is subjective" argument - I'm by no means an expert but there are many people out there who have done considerable research on human perception that there is at least room for non-subjective evaluation.  Below is my attempt.​

​If I was going to try and read it like a book I'd want the extra white-space to make doing so easier (white-space gives the eye a breather when done with a particular concept) - and the length wouldn't really matter since I'd just make a single pass and be done with it.  But the planned usage is for quick lookup of options that you know (or at least suspect) exist and which you probably have an approximate idea of how they are spelled.  The all-caps and left-justified block headers are distinct enough to scan down - though I'd consider indenting 4 spaces instead of 2 to make that even easier (less effort to ignore the indented lines since ignoring nothing is easier than ignoring something).​  Having more fit on one screen makes that vertical skimming considerably easier as well (no break and re-acquire when scrolling in a new page).

So I'll agree that in an absolute sense reading the whole of the content in its condensed form is more difficult than if there were blank lines in between each block, but usability for the intended purpose is better in the current form.

David J.

Re: [HACKERS] psql: new help related to variables are not too readable

From
Tom Lane
Date:
"David G. Johnston" <david.g.johnston@gmail.com> writes:
>​If I was going to try and read it like a book I'd want the extra
> white-space to make doing so easier (white-space gives the eye a breather
> when done with a particular concept) - and the length wouldn't really
> matter since I'd just make a single pass and be done with it.  But the
> planned usage is for quick lookup of options that you know (or at least
> suspect) exist and which you probably have an approximate idea of how they
> are spelled.  The all-caps and left-justified block headers are distinct
> enough to scan down - though I'd consider indenting 4 spaces instead of 2
> to make that even easier (less effort to ignore the indented lines since
> ignoring nothing is easier than ignoring something).​  Having more fit on
> one screen makes that vertical skimming considerably easier as well (no
> break and re-acquire when scrolling in a new page).

Hmm, indenting the descriptions a couple more spaces might be a workable
compromise.  Anyone want to try that and see what it looks like?
Preferably somebody who's not happy with the current layout ;-)
        regards, tom lane


-- 
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

Re: [HACKERS] psql: new help related to variables are not tooreadable

From
Fabien COELHO
Date:
Hello,

>> Personnally I'm fine with a pager, so vertical spacing is fine. I just do
>> not like paging horizontally.
>
> ​-1​ [...]
>
> ​If I was going to try and read it like a book I'd want the extra
> white-space to make doing so easier (white-space gives the eye a breather
> when done with a particular concept) - and the length wouldn't really
> matter since I'd just make a single pass and be done with it.  But the
> planned usage is for quick lookup of options that you know (or at least
> suspect) exist and which you probably have an approximate idea of how they
> are spelled.  The all-caps and left-justified block headers are distinct
> enough to scan down - though I'd consider indenting 4 spaces instead of 2
> to make that even easier (less effort to ignore the indented lines since
> ignoring nothing is easier than ignoring something).​  Having more fit on
> one screen makes that vertical skimming considerably easier as well (no
> break and re-acquire when scrolling in a new page).

Interesting and fine arguments!

> So I'll agree that in an absolute sense reading the whole of the content in
> its condensed form is more difficult than if there were blank lines in
> between each block, but usability for the intended purpose is better in the
> current form.

As far as usability is concerned, I most often use the "/" pager search 
feature, or page down to scan everything. Both uses are not really 
hampered by skipping lines, but I can leave with that as well.

Help formatting could be an option, but that would require more coding and 
I'm not sure of the i18n aspect.

-- 
Fabien.
-- 
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

Re: [HACKERS] psql: new help related to variables are not tooreadable

From
Alvaro Herrera
Date:
Tom Lane wrote:
> "David G. Johnston" <david.g.johnston@gmail.com> writes:
> >​If I was going to try and read it like a book I'd want the extra
> > white-space to make doing so easier (white-space gives the eye a breather
> > when done with a particular concept) - and the length wouldn't really
> > matter since I'd just make a single pass and be done with it.  But the
> > planned usage is for quick lookup of options that you know (or at least
> > suspect) exist and which you probably have an approximate idea of how they
> > are spelled.  The all-caps and left-justified block headers are distinct
> > enough to scan down - though I'd consider indenting 4 spaces instead of 2
> > to make that even easier (less effort to ignore the indented lines since
> > ignoring nothing is easier than ignoring something).​  Having more fit on
> > one screen makes that vertical skimming considerably easier as well (no
> > break and re-acquire when scrolling in a new page).
> 
> Hmm, indenting the descriptions a couple more spaces might be a workable
> compromise.  Anyone want to try that and see what it looks like?
> Preferably somebody who's not happy with the current layout ;-)

I have to admit that adding two spaces makes it look a lot more
acceptable to me.

(I'd tweak the description of PSQL_EDITOR_LINENUMBER_ARG by replacing
"how to" with "mechanism to" while at it, by the way.  It took me a
while to understand what it was and I first thought the description was
completely bogus.)

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


-- 
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

Re: [HACKERS] psql: new help related to variables are not too readable

From
Pavel Stehule
Date:


2017-09-14 15:17 GMT+02:00 Alvaro Herrera <alvherre@alvh.no-ip.org>:
Tom Lane wrote:
> "David G. Johnston" <david.g.johnston@gmail.com> writes:
> >​If I was going to try and read it like a book I'd want the extra
> > white-space to make doing so easier (white-space gives the eye a breather
> > when done with a particular concept) - and the length wouldn't really
> > matter since I'd just make a single pass and be done with it.  But the
> > planned usage is for quick lookup of options that you know (or at least
> > suspect) exist and which you probably have an approximate idea of how they
> > are spelled.  The all-caps and left-justified block headers are distinct
> > enough to scan down - though I'd consider indenting 4 spaces instead of 2
> > to make that even easier (less effort to ignore the indented lines since
> > ignoring nothing is easier than ignoring something).​  Having more fit on
> > one screen makes that vertical skimming considerably easier as well (no
> > break and re-acquire when scrolling in a new page).
>
> Hmm, indenting the descriptions a couple more spaces might be a workable
> compromise.  Anyone want to try that and see what it looks like?
> Preferably somebody who's not happy with the current layout ;-)

I have to admit that adding two spaces makes it look a lot more
acceptable to me.

I did some tests now, and when the name of variable is a upper case string, then are acceptable (although with empty line space it is better).

for pset variables (is lower case), then reading is not too friendly still.

Sure - four spaces is better than two - but readability is not good.

There can be another reason of feeling vertical spaces - the size of chars. I am using probably small fonts - I am using X windows and my typical terminal windows is half of screen (I have T520 Lenovo) about 60 rows and 120 columns. 

Please, look to document https://github.com/darold/ora2pg README and try to remove empty lines. 

Regards

Pavel
 

(I'd tweak the description of PSQL_EDITOR_LINENUMBER_ARG by replacing
"how to" with "mechanism to" while at it, by the way.  It took me a
while to understand what it was and I first thought the description was
completely bogus.)

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

Re: [HACKERS] psql: new help related to variables are not too readable

From
Pavel Stehule
Date:


2017-09-14 16:35 GMT+02:00 Pavel Stehule <pavel.stehule@gmail.com>:


2017-09-14 15:17 GMT+02:00 Alvaro Herrera <alvherre@alvh.no-ip.org>:
Tom Lane wrote:
> "David G. Johnston" <david.g.johnston@gmail.com> writes:
> >​If I was going to try and read it like a book I'd want the extra
> > white-space to make doing so easier (white-space gives the eye a breather
> > when done with a particular concept) - and the length wouldn't really
> > matter since I'd just make a single pass and be done with it.  But the
> > planned usage is for quick lookup of options that you know (or at least
> > suspect) exist and which you probably have an approximate idea of how they
> > are spelled.  The all-caps and left-justified block headers are distinct
> > enough to scan down - though I'd consider indenting 4 spaces instead of 2
> > to make that even easier (less effort to ignore the indented lines since
> > ignoring nothing is easier than ignoring something).​  Having more fit on
> > one screen makes that vertical skimming considerably easier as well (no
> > break and re-acquire when scrolling in a new page).
>
> Hmm, indenting the descriptions a couple more spaces might be a workable
> compromise.  Anyone want to try that and see what it looks like?
> Preferably somebody who's not happy with the current layout ;-)

I have to admit that adding two spaces makes it look a lot more
acceptable to me.

I did some tests now, and when the name of variable is a upper case string, then are acceptable (although with empty line space it is better).

for pset variables (is lower case), then reading is not too friendly still.

Sure - four spaces is better than two - but readability is not good.

There can be another reason of feeling vertical spaces - the size of chars. I am using probably small fonts - I am using X windows and my typical terminal windows is half of screen (I have T520 Lenovo) about 60 rows and 120 columns. 

Please, look to document https://github.com/darold/ora2pg README and try to remove empty lines. 

I am looking on man pagers - and there are very well readable

The rules are simply - when some variables are short - less than 6 chars, then it description and label are on same line. Between items are empty line - see "man less"

       ESC-} or ^RIGHTARROW
              Scroll horizontally right to show the end of the longest displayed line.

       ESC-{ or ^LEFTARROW
              Scroll horizontally left back to the first column.

       r or ^R or ^L
              Repaint the screen.

       R      Repaint  the  screen,  discarding any buffered input.  Useful if the file is changing
              while it is being viewed.

       F      Scroll forward, and keep trying to read when the end of file  is  reached.   Normally
              this command would be used when already at the end of the file.  It is a way to moni‐
              tor the tail of a file which is growing while it is being viewed.  (The  behavior  is
              similar to the "tail -f" command.)

       ESC-F  Like  F,  but  as  soon as a line is found which matches the last search pattern, the
              terminal bell is rung and forward scrolling stops.


Regards

Pavel
 

(I'd tweak the description of PSQL_EDITOR_LINENUMBER_ARG by replacing
"how to" with "mechanism to" while at it, by the way.  It took me a
while to understand what it was and I first thought the description was
completely bogus.)

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


Re: [HACKERS] psql: new help related to variables are not tooreadable

From
Alvaro Herrera
Date:
Pavel Stehule wrote:

> I am looking on man pagers - and there are very well readable
> 
> The rules are simply - when some variables are short - less than 6 chars,
> then it description and label are on same line. Between items are empty
> line

I was having a similar idea.  I'm not sure how many lines we would save
that way, but it seems to me we could use a slightly longer threshold --
say 8 chars before we cause a newline and wrap.

Maybe we need to come up with guidelines for translators, also.  As
somebody noted, I've always gone to some trouble to produce translate
output that preserves the original's constraints; I don't see any reason
forother translations to behave differently.

(By all means, if we add entry-separating newlines, let's not put them
as part of the translatable string.)

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


-- 
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

Re: [HACKERS] psql: new help related to variables are not too readable

From
Pavel Stehule
Date:


2017-09-18 11:44 GMT+02:00 Alvaro Herrera <alvherre@alvh.no-ip.org>:
Pavel Stehule wrote:

> I am looking on man pagers - and there are very well readable
>
> The rules are simply - when some variables are short - less than 6 chars,
> then it description and label are on same line. Between items are empty
> line

I was having a similar idea.  I'm not sure how many lines we would save
that way, but it seems to me we could use a slightly longer threshold --
say 8 chars before we cause a newline and wrap.

Maybe we need to come up with guidelines for translators, also.  As
somebody noted, I've always gone to some trouble to produce translate
output that preserves the original's constraints; I don't see any reason
forother translations to behave differently.

(By all means, if we add entry-separating newlines, let's not put them
as part of the translatable string.)

+1

Pavel


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