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

[Pavel Stehule]

2017-09-18 11:44 GMT+02:00 Alvaro Herrera :

> 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 Herrerahttps://www.2ndQuadrant.com/
> PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
>

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

[Alvaro Herrera]

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 Herrerahttps://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

[Pavel Stehule]

2017-09-14 16:35 GMT+02:00 Pavel Stehule :

>
>
> 2017-09-14 15:17 GMT+02:00 Alvaro Herrera :
>
>> Tom Lane wrote:
>> > "David G. Johnston"  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 Herrerahttps://www.2ndQuadrant.com/
>> PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
>>
>
>

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

[Pavel Stehule]

2017-09-14 15:17 GMT+02:00 Alvaro Herrera :

> Tom Lane wrote:
> > "David G. Johnston"  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 Herrerahttps://www.2ndQuadrant.com/
> PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
>

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

[Alvaro Herrera]

Tom Lane wrote:
> "David G. Johnston"  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 Herrerahttps://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

[Fabien COELHO]

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 too readable

[Tom Lane]

"David G. Johnston"  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 too readable

[David G. Johnston]

On Wed, Sep 13, 2017 at 12:46 PM, Fabien COELHO  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

[Fabien COELHO]

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

[Tom Lane]

Alvaro Herrera  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 too readable

[Alvaro Herrera]

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 Herrerahttps://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

[Pavel Stehule]

2017-09-13 16:11 GMT+02:00 Tom Lane :

> Fabien COELHO  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 too readable

[Tom Lane]

Fabien COELHO  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

[Fabien COELHO]

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

[Pavel Stehule]

2017-09-09 1:30 GMT+02:00 Alvaro Herrera :

> 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 Herrerahttps://www.2ndQuadrant.com/
> PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
>

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

[Alvaro Herrera]

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 Herrerahttps://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

[Daniel Verite]

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

[Tomas Vondra]

On 09/09/2017 01:24 AM, Tom Lane wrote:
> Tomas Vondra  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

  _(" "
"  ")

and

  _(" ")

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

[Pavel Stehule]

Hi

2017-09-09 1:24 GMT+02:00 Tom Lane :

> Tomas Vondra  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
>
diff --git a/src/bin/psql/help.c b/src/bin/psql/help.c
index 4d1c0ec3c6..9877cc5f55 100644
--- a/src/bin/psql/help.c
+++ b/src/bin/psql/help.c
@@ -337,7 +337,7 @@ helpVariables(unsigned short int pager)
 	 * Windows builds currently print one more line than non-Windows builds.
 	 * Using the larger number is fine.
 	 */
-	output = PageOutput(147, pager ? &(pset.popt.topt) : NULL);
+	output = PageOutput(206, pager ? &(pset.popt.topt) : NULL);
 
 	fprintf(output, _("List of specially treated variables\n\n"));
 
@@ -346,108 +346,108 @@ helpVariables(unsigned short int pager)
 	fprintf(output, _("  psql --set=NAME=VALUE\n  or \\set NAME VALUE inside psql\n\n"));
 
 	fprintf(output, _("  AUTOCOMMIT\n"
-	  "if set, successful SQL commands are automatically committed\n"));
+	  "if set, successful SQL commands are automatically committed\n\n"));
 	fprintf(output, _("  COMP_KEYWORD_CASE\n"
 	  "determines the case used to complete SQL key words\n"
-	  "[lower, upper, preserve-lower, preserve-upper]\n"));
+	  "[lower, upper, preserve-lower, preserve-upper]\n\n"));
 	fprintf(output, _("  DBNAME\n"
-	  "the currently connected database name\n"));
+	  "the currently connected database name\n\n"));
 	fprintf(output, _("  ECHO\n"
 	  "controls what input is written to standard output\n"
-	  "[all, errors, none, queries]\n"));
+	  "[all, errors, none, queries]\n\n"));
 	fprintf(output, _("  ECHO_HIDDEN\n"
 	  "if set, display internal queries executed by backslash commands;\n"
-	  "if set to \"noexec\", just show them without execution\n"));
+	  "if set to \"noexec\", just show them without execution\n\n"));
 	fprintf(output, _("  ENCODING\n"
-	  "current client character set encoding\n"));
+	  "current client character set encoding\n\n"));
 	fprintf(output, _("  FETCH_COUNT\n"
-	  "the number of result rows to fetch and display at a time (0 = unlimited)\n"));
+	  "the number of result rows to fetch and display at a time (0 = unlimited)\n\n"));
 	fprintf(output, _("  HISTCONTROL\n"
-	  "controls command history [ignorespace, ignoredups, ignoreboth]\n"));
+	  "controls command history [ignorespace, ignoredups, ignoreboth]\n\n"));
 	fprintf(output, _("  HISTFILE\n"
-	  "file name used to store the command history\n"));
+	  "file name used to store the command history\n\n"));
 	fprintf(output, _("  HISTSIZE\n"
-	  "max number of commands to store in the command history\n"));
+	  "max number of commands to store in the command history\n\n"));
 	fprintf(output, _("  HOST\n"
-	  "the currently connected database server host\n"));
+	  "the currently connected database server host\n\n"));
 	fprintf(output, _("  IGNOREEOF\n"
-	  "number of EOFs needed to terminate an interactive session\n"));
+	  "number of EOFs needed to terminate an interactive session\n\n"));
 	fprintf(output, _("  LASTOID\n"
-	  "value of the last affected OID\n"));
+	  "value of the last affected OID\n\n"));
 	fprintf(output, _("  ON_ERROR_ROLLBACK\n"
-	  "if set, an error doesn't stop a transaction (uses implicit savepoints)\n"));
+	  "if set, an error doesn't stop a transaction (uses implicit savepoints)\n\n"));
 	fprintf(output, _("  ON_ERROR_STOP\n"
-	  "stop batch execution after error\n"));
+	  "stop batch execution after error\n\n"));
 	fprintf(output, _("  PORT\n"
-	  "server port of the current connection\n"));
+	  "server port of the current connection\n\n"));
 	fprintf(output, _("  PROMPT1\n"
-	  "specifies the standard psql prompt\n"));
+	  "specifies the standard psql prompt\n\n"));
 	fprintf(output, _("  PROMPT2\n"
-	  "specifies the prompt used when a statement continues from a previous line\n"));
+	  "specifies the prompt used when a statement continues from a previous line\n\n"));
 	fprintf(output, _("  PROMPT3\n"
-	  "specifies the prompt used during COPY ... FROM STDIN\n"));
+	  "specifies the prompt used during COPY ... FROM STDIN\n\n"));
 	fprintf(output, _("  QUIET\n"
-	  "run quietly (same as -q option)\n"));
+	  "run quietly (same as -q 

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

[Tom Lane]

Tomas Vondra  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 too readable

[Tomas Vondra]

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
> 
>   XXX
>    xxx xx xxx xxx 
> 
> 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

  _(" "
"  ")

simplifies the work for translators, compared to this

  _(" ")

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

[Fabien COELHO]

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


  XXX
   xxx xx xxx xxx 

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 too readable

[Pavel Stehule]

2017-09-08 6:36 GMT+02:00 Erik Rijkers :

> 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 too readable

[Erik Rijkers]

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

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

[Pavel Stehule]

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