Thread: more i18n/l10n issues

more i18n/l10n issues

From
Alvaro Herrera
Date:
Some more comments:

#: utils/misc/guc.c:647
msgid "collect statistics about executing commands"

Is this really "statistics" about the executing commands?


#: utils/misc/guc.c:892
msgid ""
"The number must be a positive integer. If 0 is specified then effort * "
"log2(poolsize) is used"

Is it missing the final dot?


#: commands/tablecmds.c:2029
msgid "column \"%s\" is in a primary key"

So, is it in A primary key, or THE primary key?


#: commands/tablecmds.c:4093
msgid "relation \"%s\" already has a TOAST table"

This is the one place where I found it could be table instead of
relation, because it's checked explicitly in the code.  I haven't looked
very hard though, there may be others, but I've seen the last message
cleanups have changed some of them.


Now for something completely different:

The postmaster executable shows --help display perfectly localized.
However I just noted that postgres --help output (the standalone
backend) does not; is it not i18n'ed, or is some sort of missetup?

However, if I try postgres --help-config the localized display is shown,
but postmaster --help-config says

$ LC_MESSAGES=C /tmp/pgsql-es/bin/postmaster --help-config
FATAL:  --help-config requires a value

So, for some things postmaster is localized, but others are not
supported; and for some things postgres is localized, but for others
it's not.  Is this some sort of planned behavior, inconsistency, or
plain oversight?

Thanks,

-- 
Alvaro Herrera (<alvherre[a]dcc.uchile.cl>)
"Endurecerse, pero jamás perder la ternura" (E. Guevara)


Re: more i18n/l10n issues

From
Alvaro Herrera
Date:
On Sun, Sep 28, 2003 at 03:36:50PM -0400, Alvaro Herrera wrote:

> Now for something completely different:

Oh, there's another thing about the --help-config option.  This option
includes an, er, option to display the items that belong to a given
group.  So you could say

/tmp/pgsql-es/bin/postgres --help-config -g 'Security'

and the list of parameters that belong to a group that has the word
Security on it would be displayed.

However, the -l option lists the groups with the translated names, and
of course those names do not match on -g specification.

This little patch allows both versions to match, translated and
untranslated.

--
Alvaro Herrera (<alvherre[a]dcc.uchile.cl>)
"Crear es tan difícil como ser libre" (Elsa Triolet)

Attachment

Re: more i18n/l10n issues

From
Tom Lane
Date:
Alvaro Herrera <alvherre@dcc.uchile.cl> writes:
> Now for something completely different:

> The postmaster executable shows --help display perfectly localized.
> However I just noted that postgres --help output (the standalone
> backend) does not; is it not i18n'ed, or is some sort of missetup?

postgres.c's usage() isn't localized.  Dunno whether it should be or
not, given that we don't normally expect users to invoke it.

> However, if I try postgres --help-config the localized display is shown,
> but postmaster --help-config says

> $ LC_MESSAGES=C /tmp/pgsql-es/bin/postmaster --help-config
> FATAL:  --help-config requires a value

--help-config is only a postgres option.  We could possibly make it a
postmaster option too, but I'm not sure there's any need for it.
        regards, tom lane


Re: more i18n/l10n issues

From
Peter Eisentraut
Date:
Alvaro Herrera writes:

> Oh, there's another thing about the --help-config option.  This option
> includes an, er, option to display the items that belong to a given
> group.  So you could say
>
> /tmp/pgsql-es/bin/postgres --help-config -g 'Security'
>
> and the list of parameters that belong to a group that has the word
> Security on it would be displayed.
>
> However, the -l option lists the groups with the translated names, and
> of course those names do not match on -g specification.

I'm quite unhappy about the --help-config option.  It was developed
without discussion, it was installed hastily, we don't have any
information about that interactive configuration application it's supposed
to target, it's not documented, it's full of unfinished business, it
certainly doesn't make the code easier to maintain because all the
documenation is duplicated, but not one-to-one.  At this point, I wouldn't
spend a lot of time trying to make sense of it.  We can revisit it again
in the next release and investigate how we can eliminate the duplication
of effort between the documentation and the code.

> This little patch allows both versions to match, translated and
> untranslated.

That doesn't make much sense to me.  It might be that a translated word is
equal to an English word but has a different meaning.  It's also weird
that you cannot search for a complete word, e.g. "syslog", it's going to
print out all the parameters that contain "syslog".  Again, I don't think
we should worry about that now or we'll end up spending too much time on
this.

-- 
Peter Eisentraut   peter_e@gmx.net



Re: more i18n/l10n issues

From
Alvaro Herrera
Date:
On Mon, Sep 29, 2003 at 12:27:01AM +0200, Peter Eisentraut wrote:
> Alvaro Herrera writes:

> > [fixes for --help-config]

> I'm quite unhappy about the --help-config option.  It was developed
> without discussion, it was installed hastily, we don't have any
> information about that interactive configuration application it's supposed
> to target, it's not documented, it's full of unfinished business, it
> certainly doesn't make the code easier to maintain because all the
> documenation is duplicated, but not one-to-one.  At this point, I wouldn't
> spend a lot of time trying to make sense of it.

If you put it that way :-) I'll leave it alone.  I hope it can be
enhanced in the next release.  I'm not sure of it usefulness anyway;
the documentation seems good enough.


> > This little patch allows both versions to match, translated and
> > untranslated.
> 
> That doesn't make much sense to me.  It might be that a translated word is
> equal to an English word but has a different meaning.

You are probably right.  In this case may I suggest sticking the
gettext() on top of the first parameter to strstr(), so only translated
versions are found?  This makes for at least moderately sane behavior.

-- 
Alvaro Herrera (<alvherre[a]dcc.uchile.cl>)
Y una voz del caos me habló y me dijo
"Sonríe y sé feliz, podría ser peor".
Y sonreí. Y fui feliz.
Y fue peor.


Re: more i18n/l10n issues

From
Tom Lane
Date:
Alvaro Herrera <alvherre@dcc.uchile.cl> writes:
> If you put it that way :-) I'll leave it alone.  I hope it can be
> enhanced in the next release.  I'm not sure of it usefulness anyway;
> the documentation seems good enough.

Some guys at Red Hat wanted it to support an admin tool that should see
the light of day Real Soon Now.  Peter's right that it could be improved
though; in particular I would not care to defend its i18n behavior.
I've left it undocumented partly because I figure we'll be changing it.
        regards, tom lane


Re: more i18n/l10n issues

From
"Dave Page"
Date:

> -----Original Message-----
> From: Tom Lane [mailto:tgl@sss.pgh.pa.us]
> Sent: 29 September 2003 01:28
> To: Alvaro Herrera
> Cc: Peter Eisentraut; Hackers
> Subject: Re: [HACKERS] more i18n/l10n issues
>
>
> Alvaro Herrera <alvherre@dcc.uchile.cl> writes:
> > If you put it that way :-) I'll leave it alone.  I hope it can be
> > enhanced in the next release.  I'm not sure of it
> usefulness anyway;
> > the documentation seems good enough.
>
> Some guys at Red Hat wanted it to support an admin tool that
> should see the light of day Real Soon Now.  Peter's right
> that it could be improved though; in particular I would not
> care to defend its i18n behavior. I've left it undocumented
> partly because I figure we'll be changing it.

Hi Guys,

I find this a little worrying because if we want a feature or tweak for
pgAdmin we usually have to fight tooth & nail to justify getting it
committed (which is not a bad thing), however 'some guys at Red Hat' are
getting switches added to the postmaster without any discussion? I
realise they pay the wages of at least one of the developers many of us
depend on, but surely they should have to justify their modifications as
the rest of us do?

Regards, Dave.


Re: more i18n/l10n issues

From
Peter Eisentraut
Date:
Dave Page writes:

> I find this a little worrying because if we want a feature or tweak for
> pgAdmin we usually have to fight tooth & nail to justify getting it
> committed (which is not a bad thing), however 'some guys at Red Hat' are
> getting switches added to the postmaster without any discussion?

It was not a nice thing to do.

Could whoever is responsible for this admin tool at Red Hat please specify
exactly what data they need out of this interface, so we have a chance to
make the interface a little more future-proof now and possibly remove some
of the unneeded clutter that is giving translators problems?  Surely that
would be in everyone's interest, because if we're already set on changing
the feature again pretty soon, it won't do that admin tool much good.

-- 
Peter Eisentraut   peter_e@gmx.net



Re: more i18n/l10n issues

From
Andreas Pflug
Date:
Peter Eisentraut wrote:

>Dave Page writes:
>
>  
>
>>I find this a little worrying because if we want a feature or tweak for
>>pgAdmin we usually have to fight tooth & nail to justify getting it
>>committed (which is not a bad thing), however 'some guys at Red Hat' are
>>getting switches added to the postmaster without any discussion?
>>    
>>
>
>It was not a nice thing to do.
>
>Could whoever is responsible for this admin tool at Red Hat please specify
>exactly what data they need out of this interface, so we have a chance to
>make the interface a little more future-proof now and possibly remove some
>of the unneeded clutter that is giving translators problems?  Surely that
>would be in everyone's interest, because if we're already set on changing
>the feature again pretty soon, it won't do that admin tool much good.
>
I'm just wondering what this new admin tools is about, what's so 
different about it compared to existing ones making the re-invention of 
the wheel necessary...

Regards,
Andreas

>
>  
>




Re: more i18n/l10n issues

From
Tom Lane
Date:
Peter Eisentraut <peter_e@gmx.net> writes:
> Dave Page writes:
>> I find this a little worrying because if we want a feature or tweak for
>> pgAdmin we usually have to fight tooth & nail to justify getting it
>> committed (which is not a bad thing), however 'some guys at Red Hat' are
>> getting switches added to the postmaster without any discussion?

> It was not a nice thing to do.

Gimme a break, guys.  There *was* discussion, eg here,
http://archives.postgresql.org/pgsql-hackers/2003-06/msg01092.php
and the patch was posted for review, see this thread:
http://archives.postgresql.org/pgsql-patches/2003-06/msg00420.php

I'll admit that I applied the patch with more than usual speed, but that
was because we were right up against our self-imposed feature freeze
deadline for 7.4, and I didn't see any big objections.  The biggest
gripe left over at the end of the above-mentioned patches thread was that
the message texts were unpolished, but as even Peter agreed, that could
be fixed later.  So MHO is let's fix them now.

> Could whoever is responsible for this admin tool at Red Hat please specify
> exactly what data they need out of this interface, so we have a chance to
> make the interface a little more future-proof now and possibly remove some
> of the unneeded clutter that is giving translators problems?

The point was to allow a GUI utility to be built that would help in
editing postgresql.conf.  It couldn't assume the postmaster is already
running, so just extending the pg_config view wouldn't answer, and
duplicating knowledge of all the GUC variables in a separate tool
would have created maintenance headaches.  I would like to think that
the patch would eventually allow us to generate postgresql.conf.sample
automatically from the guc.c tables, and thereby reduce the number of
files to maintain, but that didn't get done yet.  The reason for having
both "long" and "short" descriptions of the variables was that I foresaw
the "short" versions as becoming the per-line comments in
postgresql.conf.  The "long" descriptions were what the GUI tool wants.
        regards, tom lane


Re: more i18n/l10n issues

From
"Dave Page"
Date:

> -----Original Message-----
> From: Tom Lane [mailto:tgl@sss.pgh.pa.us]
> Sent: 29 September 2003 15:23
> To: Peter Eisentraut
> Cc: Dave Page; Alvaro Herrera; Hackers
> Subject: Re: [HACKERS] more i18n/l10n issues
>
>
> Peter Eisentraut <peter_e@gmx.net> writes:
> > Dave Page writes:
> >> I find this a little worrying because if we want a feature
> or tweak
> >> for pgAdmin we usually have to fight tooth & nail to
> justify getting
> >> it committed (which is not a bad thing), however 'some guys at Red
> >> Hat' are getting switches added to the postmaster without any
> >> discussion?
>
> > It was not a nice thing to do.
>
> Gimme a break, guys.  There *was* discussion, eg here,
> http://archives.postgresql.org/pgsql-hackers/2003-06/msg01092.php
> and the patch was posted for review, see this thread:
> http://archives.postgresql.org/pgsql-patches/2003-06/msg00420.php

My apologes - I was basing my comments on someone else's assertion that
there was no discussion.

Regards, Dave.


Re: more i18n/l10n issues

From
Bruce Momjian
Date:
Should we allow SHOW ALL to show these variable descriptions?

---------------------------------------------------------------------------

Tom Lane wrote:
> Peter Eisentraut <peter_e@gmx.net> writes:
> > Dave Page writes:
> >> I find this a little worrying because if we want a feature or tweak for
> >> pgAdmin we usually have to fight tooth & nail to justify getting it
> >> committed (which is not a bad thing), however 'some guys at Red Hat' are
> >> getting switches added to the postmaster without any discussion?
> 
> > It was not a nice thing to do.
> 
> Gimme a break, guys.  There *was* discussion, eg here,
> http://archives.postgresql.org/pgsql-hackers/2003-06/msg01092.php
> and the patch was posted for review, see this thread:
> http://archives.postgresql.org/pgsql-patches/2003-06/msg00420.php
> 
> I'll admit that I applied the patch with more than usual speed, but that
> was because we were right up against our self-imposed feature freeze
> deadline for 7.4, and I didn't see any big objections.  The biggest
> gripe left over at the end of the above-mentioned patches thread was that
> the message texts were unpolished, but as even Peter agreed, that could
> be fixed later.  So MHO is let's fix them now.
> 
> > Could whoever is responsible for this admin tool at Red Hat please specify
> > exactly what data they need out of this interface, so we have a chance to
> > make the interface a little more future-proof now and possibly remove some
> > of the unneeded clutter that is giving translators problems?
> 
> The point was to allow a GUI utility to be built that would help in
> editing postgresql.conf.  It couldn't assume the postmaster is already
> running, so just extending the pg_config view wouldn't answer, and
> duplicating knowledge of all the GUC variables in a separate tool
> would have created maintenance headaches.  I would like to think that
> the patch would eventually allow us to generate postgresql.conf.sample
> automatically from the guc.c tables, and thereby reduce the number of
> files to maintain, but that didn't get done yet.  The reason for having
> both "long" and "short" descriptions of the variables was that I foresaw
> the "short" versions as becoming the per-line comments in
> postgresql.conf.  The "long" descriptions were what the GUI tool wants.
> 
>             regards, tom lane
> 
> ---------------------------(end of broadcast)---------------------------
> TIP 1: subscribe and unsubscribe commands go to majordomo@postgresql.org
> 

--  Bruce Momjian                        |  http://candle.pha.pa.us pgman@candle.pha.pa.us               |  (610)
359-1001+  If your life is a hard drive,     |  13 Roberts Road +  Christ can be your backup.        |  Newtown Square,
Pennsylvania19073
 


Re: more i18n/l10n issues

From
Bruce Momjian
Date:
And maybe show the descriptions in pg_settings too?

---------------------------------------------------------------------------

Tom Lane wrote:
> Peter Eisentraut <peter_e@gmx.net> writes:
> > Dave Page writes:
> >> I find this a little worrying because if we want a feature or tweak for
> >> pgAdmin we usually have to fight tooth & nail to justify getting it
> >> committed (which is not a bad thing), however 'some guys at Red Hat' are
> >> getting switches added to the postmaster without any discussion?
> 
> > It was not a nice thing to do.
> 
> Gimme a break, guys.  There *was* discussion, eg here,
> http://archives.postgresql.org/pgsql-hackers/2003-06/msg01092.php
> and the patch was posted for review, see this thread:
> http://archives.postgresql.org/pgsql-patches/2003-06/msg00420.php
> 
> I'll admit that I applied the patch with more than usual speed, but that
> was because we were right up against our self-imposed feature freeze
> deadline for 7.4, and I didn't see any big objections.  The biggest
> gripe left over at the end of the above-mentioned patches thread was that
> the message texts were unpolished, but as even Peter agreed, that could
> be fixed later.  So MHO is let's fix them now.
> 
> > Could whoever is responsible for this admin tool at Red Hat please specify
> > exactly what data they need out of this interface, so we have a chance to
> > make the interface a little more future-proof now and possibly remove some
> > of the unneeded clutter that is giving translators problems?
> 
> The point was to allow a GUI utility to be built that would help in
> editing postgresql.conf.  It couldn't assume the postmaster is already
> running, so just extending the pg_config view wouldn't answer, and
> duplicating knowledge of all the GUC variables in a separate tool
> would have created maintenance headaches.  I would like to think that
> the patch would eventually allow us to generate postgresql.conf.sample
> automatically from the guc.c tables, and thereby reduce the number of
> files to maintain, but that didn't get done yet.  The reason for having
> both "long" and "short" descriptions of the variables was that I foresaw
> the "short" versions as becoming the per-line comments in
> postgresql.conf.  The "long" descriptions were what the GUI tool wants.
> 
>             regards, tom lane
> 
> ---------------------------(end of broadcast)---------------------------
> TIP 1: subscribe and unsubscribe commands go to majordomo@postgresql.org
> 

--  Bruce Momjian                        |  http://candle.pha.pa.us pgman@candle.pha.pa.us               |  (610)
359-1001+  If your life is a hard drive,     |  13 Roberts Road +  Christ can be your backup.        |  Newtown Square,
Pennsylvania19073
 


Re: more i18n/l10n issues

From
Andrew Dunstan
Date:
Tom Lane wrote:

>
>The point was to allow a GUI utility to be built that would help in
>editing postgresql.conf.  It couldn't assume the postmaster is already
>running, so just extending the pg_config view wouldn't answer, and
>duplicating knowledge of all the GUC variables in a separate tool
>would have created maintenance headaches.  I would like to think that
>the patch would eventually allow us to generate postgresql.conf.sample
>automatically from the guc.c tables, and thereby reduce the number of
>files to maintain, but that didn't get done yet.  The reason for having
>both "long" and "short" descriptions of the variables was that I foresaw
>the "short" versions as becoming the per-line comments in
>postgresql.conf.  The "long" descriptions were what the GUI tool wants.
>
>  
>
I have been wondering if moving to XML for config files might be a good 
idea - and if there are going to be GUIs that write them that gives some 
more impetus to the idea.

This occurred to me as I was writing the token replacement stuff for 
initdb.c, and I realised how fragile it was - a misplaced space and you 
are hosed.

Or would it be overkill?

cheers

andrew



Re: more i18n/l10n issues

From
Tom Lane
Date:
Bruce Momjian <pgman@candle.pha.pa.us> writes:
> And maybe show the descriptions in pg_settings too?

There was discussion of doing that, but it didn't get done in time
(and it's too late now for 7.4 unless you want an initdb).  I wouldn't
mind putting it on TODO for 7.5.

I think the SHOW ALL output should be kept to one line per variable,
which'd preclude adding "long" descriptions, but we could think about
adding the "short" ones.  (I have no similar worry about pg_settings
because one can easily choose which columns one looks at.)
        regards, tom lane


Re: more i18n/l10n issues

From
Bruce Momjian
Date:
Joe Conway wrote:
> Tom Lane wrote:
> > Bruce Momjian <pgman@candle.pha.pa.us> writes:
> >>And maybe show the descriptions in pg_settings too?
> > 
> > There was discussion of doing that, but it didn't get done in time
> > (and it's too late now for 7.4 unless you want an initdb).  I wouldn't
> > mind putting it on TODO for 7.5.
> 
> Bruce, you can put my name next to that TODO.
> 
> > I think the SHOW ALL output should be kept to one line per variable,
> > which'd preclude adding "long" descriptions, but we could think about
> > adding the "short" ones.  (I have no similar worry about pg_settings
> > because one can easily choose which columns one looks at.)
> 
> This one too.

Added to TODO:
 * Have SHOW ALL and pg_settings show descriptions for server-side   variables(Joe)

--  Bruce Momjian                        |  http://candle.pha.pa.us pgman@candle.pha.pa.us               |  (610)
359-1001+  If your life is a hard drive,     |  13 Roberts Road +  Christ can be your backup.        |  Newtown Square,
Pennsylvania19073
 


Re: more i18n/l10n issues

From
Joe Conway
Date:
Tom Lane wrote:
> Bruce Momjian <pgman@candle.pha.pa.us> writes:
>>And maybe show the descriptions in pg_settings too?
> 
> There was discussion of doing that, but it didn't get done in time
> (and it's too late now for 7.4 unless you want an initdb).  I wouldn't
> mind putting it on TODO for 7.5.

Bruce, you can put my name next to that TODO.

> I think the SHOW ALL output should be kept to one line per variable,
> which'd preclude adding "long" descriptions, but we could think about
> adding the "short" ones.  (I have no similar worry about pg_settings
> because one can easily choose which columns one looks at.)

This one too.

Joe



Re: more i18n/l10n issues

From
Peter Eisentraut
Date:
Alvaro Herrera writes:

> #: utils/misc/guc.c:647
> msgid "collect statistics about executing commands"
>
> Is this really "statistics" about the executing commands?

Looks like it.

> #: utils/misc/guc.c:892
> msgid ""
> "The number must be a positive integer. If 0 is specified then effort * "
> "log2(poolsize) is used"
>
> Is it missing the final dot?

Added.

> #: commands/tablecmds.c:2029
> msgid "column \"%s\" is in a primary key"
>
> So, is it in A primary key, or THE primary key?

The message doesn't mention a table, so "the primary key" would just stand
without reference.  I think both have merits.

> #: commands/tablecmds.c:4093
> msgid "relation \"%s\" already has a TOAST table"
>
> This is the one place where I found it could be table instead of
> relation, because it's checked explicitly in the code.

True.  I've also changed a few messages around that one.

> The postmaster executable shows --help display perfectly localized.
> However I just noted that postgres --help output (the standalone
> backend) does not; is it not i18n'ed, or is some sort of missetup?

It was not set up for gettext, but it is now.

-- 
Peter Eisentraut   peter_e@gmx.net



Re: more i18n/l10n issues

From
Tom Lane
Date:
Andrew Dunstan <andrew@dunslane.net> writes:
> I have been wondering if moving to XML for config files might be a good 
> idea - and if there are going to be GUIs that write them that gives some 
> more impetus to the idea.

> Or would it be overkill?

Seems like overkill.  What would it buy us, other than making it a lot
more painful to edit the config files manually?
        regards, tom lane


Re: more i18n/l10n issues

From
Peter Eisentraut
Date:
Andrew Dunstan writes:

> I have been wondering if moving to XML for config files might be a good
> idea - and if there are going to be GUIs that write them that gives some
> more impetus to the idea.

What I would like to see done is keeping the GUC data, that is, the name,
the properties, and the description, in some certralized store and
generate code and documentation from that.  It could be done with XML,
SGML, m4 -- I don't care.

-- 
Peter Eisentraut   peter_e@gmx.net



Re: more i18n/l10n issues

From
Peter Eisentraut
Date:
Tom Lane writes:

> Gimme a break, guys.  There *was* discussion, eg here,
> http://archives.postgresql.org/pgsql-hackers/2003-06/msg01092.php
> and the patch was posted for review, see this thread:
> http://archives.postgresql.org/pgsql-patches/2003-06/msg00420.php

I confused this with the private mails that we exchanged.  Sorry.

> The point was to allow a GUI utility to be built that would help in
> editing postgresql.conf.  It couldn't assume the postmaster is already
> running, so just extending the pg_config view wouldn't answer, and
> duplicating knowledge of all the GUC variables in a separate tool
> would have created maintenance headaches.

OK, but does this tool actually need all of the following features:

-G -- do not group by category
both -m and -M -- machine-readable output with and without header
human-readable output

Were some of these just added for "completeness"?  With what rationale?

Also, --help-config 'foo' outputs all parameters matching 'foo' somewhere
in the string, not only 'foo'.  I think that is a misdesign.

> I would like to think that
> the patch would eventually allow us to generate postgresql.conf.sample
> automatically from the guc.c tables, and thereby reduce the number of
> files to maintain, but that didn't get done yet.  The reason for having
> both "long" and "short" descriptions of the variables was that I foresaw
> the "short" versions as becoming the per-line comments in
> postgresql.conf.  The "long" descriptions were what the GUI tool wants.

Most parameters don't have long descriptions, so that doesn't seem right.

Also, in many cases where there is a long description, it was copied out
of the documentation, with the short description being the first sentence
and the long description being the rest.  The result is that in some cases
the long description doesn't make sense in isolation.  I would like that
to be clarified.

-- 
Peter Eisentraut   peter_e@gmx.net



Re: more i18n/l10n issues

From
Bruce Momjian
Date:
Peter Eisentraut wrote:
> Andrew Dunstan writes:
> 
> > I have been wondering if moving to XML for config files might be a good
> > idea - and if there are going to be GUIs that write them that gives some
> > more impetus to the idea.
> 
> What I would like to see done is keeping the GUC data, that is, the name,
> the properties, and the description, in some centralized store and
> generate code and documentation from that.  It could be done with XML,
> SGML, m4 -- I don't care.

Yes, the use of SGML files by psql help is brilliant.

--  Bruce Momjian                        |  http://candle.pha.pa.us pgman@candle.pha.pa.us               |  (610)
359-1001+  If your life is a hard drive,     |  13 Roberts Road +  Christ can be your backup.        |  Newtown Square,
Pennsylvania19073
 


Re: more i18n/l10n issues

From
Tom Lane
Date:
Peter Eisentraut <peter_e@gmx.net> writes:
> [ some fair points ]

I've asked the Red Hat folks who did the detail design to respond to
this.  I'm not sure if they had specific use-cases in mind for those 
behaviors, or were just trying to make the feature useful for manual
invocation.  I would think the GUI tool doesn't need most of those
behaviors, but can't swear to it.
        regards, tom lane


Re: more i18n/l10n issues

From
Tom Lane
Date:
Peter Eisentraut <peter_e@gmx.net> writes:
> [ some questions about --help-config ]

I got this reply from Fernando Nasser of Red Hat.  I suggested he should
post it for himself, but since he hasn't yet...
        regards, tom lane

> ------- Forwarded Message
> 
> Date:    Tue, 30 Sep 2003 11:24:50 +0200 (CEST)
> From:    Peter Eisentraut <peter_e@gmx.net>
(...)
> 
> OK, but does this tool actually need all of the following features:
> 
> -G -- do not group by category
> both -m and -M -- machine-readable output with and without header
> human-readable output
> > Were some of these just added for "completeness"?  With what rationale?>


-m and -M

The utility we designed and possibly any other that wants to process the 
output will find it easier to process a more regularly formed output 
instead of one that was embellished for human viewing.  The reason for 
having one with and one without headings is that in some circumstances 
the utility designer may want to use the headers to make her/his table 
headers and others may prefer to have pre-defined table headers.  The 
guy who wrote our window used -M while I would have liked him to use -m 
(but -M was faster to do and he was on a hurry).

-G

The -G (using the Unix convention of negating things with capital 
letters) is what we use.  This option is probably what will be used for 
generating the postgresql.conf default file automatically.
As we were not adding a facility for our use but for other tool 
developers as well and we thought that some may want to process it in 
different ways we made it an option.  We don't object making it a side 
effect of using -m or -M.



> Also, --help-config 'foo' outputs all parameters matching 'foo' somewhere
> in the string, not only 'foo'.  I think that is a misdesign.
> 

It works like locate (or slocate). I believe some other Unix utilities 
do the same.  Unix commands are mostly 'misdesigned' I admit.

I had a '-re' which accepted a regular expression. With that re-added 
one could make the --help-config 'foo' works like Peter wants.  But I 
would put that for a vote: I wouldn't be surprised if Peter were in a 
minority on this issue.


>>postgresql.conf.  The "long" descriptions were what the GUI tool wants.
> 

Tom, actually the tool (as I believe from previous experience with 
command line help facilities) needs both.

The short description shows up in summaries where you have a list of 
options and not much space.  The long description shows up in specific 
help commands, as tooltips etc., whenever the user wants and you can 
provide more information.

> 
> Most parameters don't have long descriptions, so that doesn't seem right.
> 

When the meaning is obvious there is no need to re-state it.  There may 
be cases where a better description should be written and it is only 
empty because nobody yet knows exactly what it does, or could not come 
up with a proper description (whenever a description was available in 
the documentation the field was filled).


> Also, in many cases where there is a long description, it was copied out
> of the documentation, with the short description being the first sentence
> and the long description being the rest.  The result is that in some cases
> the long description doesn't make sense in isolation.  I would like that
> to be clarified.
> 

This is a GNU trick to avoid repeating the same text (from the short 
description) in the long description.  I believe it is from Richard 
Stallman's time.  It is used in several GNU tools, for instance the GNU 
GDB debugger (which uses just one field and makes the first sentence or 
line the short description). The idea is that the long description is 
formed by the concatenation of the two.

-- 
Fernando Nasser
Red Hat Canada Ltd.                     E-Mail:  fnasser@redhat.com
2323 Yonge Street, Suite #300
Toronto, Ontario   M4P 2C9

------- End of Forwarded Message



postgres --help-config

From
Bruce Momjian
Date:
Where should I start on this?  :-)

The implementation of postgres --help-config has several issues:
o  it has options added "just in case someone ever need them"o  it has capital letters to negate, which we have never
used  beforeo  uses GNU message reporting styleo  there was little discussion about how this should work
 

Its biggest "plus" is that it isn't documented :-) --- because the API
might change in the next release, and no one wants to stand up for this.

If Red Hat didn't do so much for PostgreSQL by hiring Tom and others, I
would be more upset, but putting something in for the convenience of
some Red Hat tool isn't something I would like to see happen regularly,
and I think we can all agree on that.

I can't even put a mention on the TODO that this has to be cleaned up
because I would then advertise it.  I will put it on my personal list
and we can discuss how this is supposed to for for 7.5.

---------------------------------------------------------------------------

Tom Lane wrote:
> Peter Eisentraut <peter_e@gmx.net> writes:
> > [ some questions about --help-config ]
> 
> I got this reply from Fernando Nasser of Red Hat.  I suggested he should
> post it for himself, but since he hasn't yet...
> 
>             regards, tom lane
> 
> > ------- Forwarded Message
> > 
> > Date:    Tue, 30 Sep 2003 11:24:50 +0200 (CEST)
> > From:    Peter Eisentraut <peter_e@gmx.net>
> (...)
> > 
> > OK, but does this tool actually need all of the following features:
> > 
> > -G -- do not group by category
> > both -m and -M -- machine-readable output with and without header
> > human-readable output
> > 
>  > Were some of these just added for "completeness"?  With what rationale?
>  >
> 
> 
> -m and -M
> 
> The utility we designed and possibly any other that wants to process the 
> output will find it easier to process a more regularly formed output 
> instead of one that was embellished for human viewing.  The reason for 
> having one with and one without headings is that in some circumstances 
> the utility designer may want to use the headers to make her/his table 
> headers and others may prefer to have pre-defined table headers.  The 
> guy who wrote our window used -M while I would have liked him to use -m 
> (but -M was faster to do and he was on a hurry).
> 
> -G
> 
> The -G (using the Unix convention of negating things with capital 
> letters) is what we use.  This option is probably what will be used for 
> generating the postgresql.conf default file automatically.
> As we were not adding a facility for our use but for other tool 
> developers as well and we thought that some may want to process it in 
> different ways we made it an option.  We don't object making it a side 
> effect of using -m or -M.
> 
> 
> 
> > Also, --help-config 'foo' outputs all parameters matching 'foo' somewhere
> > in the string, not only 'foo'.  I think that is a misdesign.
> > 
> 
> It works like locate (or slocate). I believe some other Unix utilities 
> do the same.  Unix commands are mostly 'misdesigned' I admit.
> 
> I had a '-re' which accepted a regular expression. With that re-added 
> one could make the --help-config 'foo' works like Peter wants.  But I 
> would put that for a vote: I wouldn't be surprised if Peter were in a 
> minority on this issue.
> 
> 
> >>postgresql.conf.  The "long" descriptions were what the GUI tool wants.
> > 
> 
> Tom, actually the tool (as I believe from previous experience with 
> command line help facilities) needs both.
> 
> The short description shows up in summaries where you have a list of 
> options and not much space.  The long description shows up in specific 
> help commands, as tooltips etc., whenever the user wants and you can 
> provide more information.
> 
> > 
> > Most parameters don't have long descriptions, so that doesn't seem right.
> > 
> 
> When the meaning is obvious there is no need to re-state it.  There may 
> be cases where a better description should be written and it is only 
> empty because nobody yet knows exactly what it does, or could not come 
> up with a proper description (whenever a description was available in 
> the documentation the field was filled).
> 
> 
> > Also, in many cases where there is a long description, it was copied out
> > of the documentation, with the short description being the first sentence
> > and the long description being the rest.  The result is that in some cases
> > the long description doesn't make sense in isolation.  I would like that
> > to be clarified.
> > 
> 
> This is a GNU trick to avoid repeating the same text (from the short 
> description) in the long description.  I believe it is from Richard 
> Stallman's time.  It is used in several GNU tools, for instance the GNU 
> GDB debugger (which uses just one field and makes the first sentence or 
> line the short description). The idea is that the long description is 
> formed by the concatenation of the two.
> 
> -- 
> Fernando Nasser
> Red Hat Canada Ltd.                     E-Mail:  fnasser@redhat.com
> 2323 Yonge Street, Suite #300
> Toronto, Ontario   M4P 2C9
> 
> ------- End of Forwarded Message
> 
> 
> ---------------------------(end of broadcast)---------------------------
> TIP 4: Don't 'kill -9' the postmaster
> 

--  Bruce Momjian                        |  http://candle.pha.pa.us pgman@candle.pha.pa.us               |  (610)
359-1001+  If your life is a hard drive,     |  13 Roberts Road +  Christ can be your backup.        |  Newtown Square,
Pennsylvania19073
 


Re: postgres --help-config

From
Tom Lane
Date:
Bruce Momjian <pgman@candle.pha.pa.us> writes:
> Where should I start on this?  :-)

Where should I start on all the people who are complaining now, but
said not a word when the patch was put up for review?

I'm quite annoyed at these claims that procedure wasn't followed.
It's either selective memory or historical revisionism, and either
way I feel it's unfair to me and to Red Hat.

Let's see some specific suggestions for improvement, rather than
bootless complaining.  I'm quite prepared to agree that the patch
could use improvement.  If we can fix it before 7.4 release,
let's do so.
        regards, tom lane


Re: postgres --help-config

From
Bruce Momjian
Date:
Tom Lane wrote:
> Bruce Momjian <pgman@candle.pha.pa.us> writes:
> > Where should I start on this?  :-)
> 
> Where should I start on all the people who are complaining now, but
> said not a word when the patch was put up for review?
> 
> I'm quite annoyed at these claims that procedure wasn't followed.
> It's either selective memory or historical revisionism, and either
> way I feel it's unfair to me and to Red Hat.
> 
> Let's see some specific suggestions for improvement, rather than
> bootless complaining.  I'm quite prepared to agree that the patch
> could use improvement.  If we can fix it before 7.4 release,
> let's do so.

Oh, OK.  I thought you wanted it unchanged in the code, and we were
going to deail with it later.  It just doesn't _seem_ to match our
style.  Let me look at it and I will repost.

--  Bruce Momjian                        |  http://candle.pha.pa.us pgman@candle.pha.pa.us               |  (610)
359-1001+  If your life is a hard drive,     |  13 Roberts Road +  Christ can be your backup.        |  Newtown Square,
Pennsylvania19073
 


Re: postgres --help-config

From
Bruce Momjian
Date:
Tom Lane wrote:
> Bruce Momjian <pgman@candle.pha.pa.us> writes:
> > Where should I start on this?  :-)
> 
> Where should I start on all the people who are complaining now, but
> said not a word when the patch was put up for review?
> 
> I'm quite annoyed at these claims that procedure wasn't followed.
> It's either selective memory or historical revisionism, and either
> way I feel it's unfair to me and to Red Hat.
> 
> Let's see some specific suggestions for improvement, rather than
> bootless complaining.  I'm quite prepared to agree that the patch
> could use improvement.  If we can fix it before 7.4 release,
> let's do so.

OK, I have some ideas.  Because you didn't document it, and couldn't get
Fernando to post a reply to Peter's questions, I assumed you didn't want
to work on it right now, and that it was in there just for Red Hat.

First, the default output should have the sorted field first.  It
appears the default is to sort by context:
postgres --help-config

That should be the first printed field.  However, I see you can sort by
Group, so maybe group should always be first --- that seems most
logical.

The documentation I see is the command-line help in the C file:
   printf(gettext("Usage:\n  %s --help-config [OPTION]... [NAME]\n\n"), progname);   printf(gettext("General
Options:\n"));  printf(gettext("  NAME      output information about parameters matching this name\n"));
printf(gettext(" -g GROUP  output information about parameters matching this group\n"));   printf(gettext("  -l
listavailable parameter groups\n"));   printf(gettext("  -h        show this help, then exit\n"));
printf(gettext("\nOutputOptions:\n"));   printf(gettext("  -G  do not group by category\n"));   printf(gettext("  -m
machine-friendlyformat: tab separated fields\n"));   printf(gettext("  -M  same as -m, but header with column names is
suppressed\n"));

I don't see any value to most of these parameters, and the "add them in
case they might need them" has never been our philosophy, so I don't see
why we should add them at this point.  Can we just get minimal
functionality and see what people ask for --- they might ask for
something completely different from what we have spec'ed out here, and
if they do, we will have to remove existing options to meet their needs,
or maintain a bloat of options.  You know I have no problems adding
options to make common tasks easier for our users, but we have no usage
cases yet to know what they want.

What would make sense is to always output sorted by Group/Name, and see
how that works for folks.  I also didn't think the dashed lines were
needed --- they seemed to clutter the output:
------------------------------------------------------------Name:          preload_librariesContext:
postmasterGroup:        Resource Usage / Kernel ResourcesType:          stringDefault value:Description:   shared
librariesto preload into server------------------------------------------------------------Name:          fsyncContext:
     sighupGroup:         Write-Ahead Log / SettingsType:          BooleanDefault value: trueDescription:   force
synchronizationof updates to diskThe server will use the fsync() system call in several places to make sure that
updatesare physically written to disk. This insures that a database cluster will recover to a consistent state after an
operatingsystem or hardware crash.------------------------------------------------------------
 

vs.
Name:          preload_librariesContext:       postmasterGroup:         Resource Usage / Kernel ResourcesType:
stringDefaultvalue:Description:   shared libraries to preload into serverName:          fsyncContext:
sighupGroup:        Write-Ahead Log / SettingsType:          BooleanDefault value: trueDescription:   force
synchronizationof updates to diskThe server will use the fsync() system call in several places to make sure that
updatesare physically written to disk. This insures that a database cluster will recover to a consistent state after an
operatingsystem or hardware crash.
 

An output that uses --help-config, and takes no flags seems like the way
to go at this point.  If people want specific entries, they can page
through them with less, or use a tool to extract them from the text file
--- the output is in a very clear format.

I would also indent the text description (last line) to line up with the
other data fields.

Is that enough feedback?  :-)

--  Bruce Momjian                        |  http://candle.pha.pa.us pgman@candle.pha.pa.us               |  (610)
359-1001+  If your life is a hard drive,     |  13 Roberts Road +  Christ can be your backup.        |  Newtown Square,
Pennsylvania19073
 


Re: more i18n/l10n issues

From
Peter Eisentraut
Date:
Tom Lane writes:

> -m and -M
>
> The utility we designed and possibly any other that wants to process the
> output will find it easier to process a more regularly formed output
> instead of one that was embellished for human viewing.  The reason for
> having one with and one without headings is that in some circumstances
> the utility designer may want to use the headers to make her/his table
> headers and others may prefer to have pre-defined table headers.  The
> guy who wrote our window used -M while I would have liked him to use -m
> (but -M was faster to do and he was on a hurry).

But the headers output by -m are not useful for human viewing.  Also, we
don't have any ideas what "utility designers" may want, we only know what
your tool wants.  So unless you need both -m and -M, I propose that we
remove the option with headers and make -m output the list without
headers.

> -G
>
> The -G (using the Unix convention of negating things with capital
> letters) is what we use.  This option is probably what will be used for
> generating the postgresql.conf default file automatically.
> As we were not adding a facility for our use but for other tool
> developers as well and we thought that some may want to process it in
> different ways we made it an option.  We don't object making it a side
> effect of using -m or -M.

If you aren't using the group-by-category option, then I propose that we
remove it.  We haven't heard any proposals about generating
postgresql.conf, or about any other tool developers, so it's pure fantasy
at this point.  I don't like comitting to features based on fantasies.

> > Also, --help-config 'foo' outputs all parameters matching 'foo' somewhere
> > in the string, not only 'foo'.  I think that is a misdesign.
> >
>
> It works like locate (or slocate). I believe some other Unix utilities
> do the same.  Unix commands are mostly 'misdesigned' I admit.

If I enter "ls foo", it shows me only foo.  If I enter "rm foo", it only
removes foo.  Works perfectly well.  If you want a wildcarding behavior,
it should be explicit.  Also note that locate provides a way to make the
search string anchored, whereas your design does not.  How does you tool
work if the user wants to take a look at the option "geqo"?  It will then
show all options that contain "geqo".  There is no way to look at only one
option and that seems wrong.  So I propose that the match-anywhere
behavior be removed.

> > Also, in many cases where there is a long description, it was copied out
> > of the documentation, with the short description being the first sentence
> > and the long description being the rest.  The result is that in some cases
> > the long description doesn't make sense in isolation.  I would like that
> > to be clarified.
> >
>
> This is a GNU trick to avoid repeating the same text (from the short
> description) in the long description.  I believe it is from Richard
> Stallman's time.  It is used in several GNU tools, for instance the GNU
> GDB debugger (which uses just one field and makes the first sentence or
> line the short description). The idea is that the long description is
> formed by the concatenation of the two.

If you want to pull tricks like that, you need to tell us about it.
Right now, some of that doesn't work anymore, because some of the short
and long descriptions had to be reworked to make sense in isolation.

I think what I would like to do for the next release is to rip out all of
this and store the information about the configuration parameters in some
external file and generate code, documentation, and help from that.  Then
we can have a short and a long description without any tricks.

-- 
Peter Eisentraut   peter_e@gmx.net



Re: postgres --help-config

From
Tom Lane
Date:
[ back from San Jose, catching up on email ]

Bruce Momjian <pgman@candle.pha.pa.us> writes:
> Is that enough feedback?  :-)

Yup, thanks for the comments.  I am not sure how much of the existing
--help-config functionality is actually needed by Red Hat's tool, so
I've asked those guys to respond.

Personally I agree with the idea of stripping out whatever functionality
isn't immediately necessary.  It seems to me we've generally been more
successful by adding features in response to specific demand rather than
inventing things we think might be needed.
        regards, tom lane


Re: postgres --help-config

From
Fernando Nasser
Date:
Bruce,

Before I comment on your suggestions, I would like to mention that many of the 
things below were added on request by the few people who cared to comment on it.  Aizaz spent most of his time changing
hereand there to accommodate these 
 
requests.  Anyway, we know we can't satisfy all, but I wish people would be more 
timely when criticizing things.  Aizaz is away until May and left thinking 
everything was under control.  And we developed a very nice tool that depends on 
this feature confident that we could count on it.


Bruce Momjian wrote:> Tom Lane wrote:
> 
> First, the default output should have the sorted field first.  It
> appears the default is to sort by context:
> 
>     postgres --help-config
> 
> That should be the first printed field.  However, I see you can sort by
> Group, so maybe group should always be first --- that seems most
> logical.
> 

Whatever you do to the human-readable output, please don't change the -M/-m 
format.  It makes it harder to write code to parse these things if the fields 
keep changing positions.

Someone is supposed to write an utility to create the sample postgresql.conf 
file from the output as well.  I believe this tool would use it without the -G 
so that is why we have the -G option. Also, it was deemed better for the user 
readable output to have it grouped (it is easier to check with the documentation 
as well when it is being reviewed).


> The documentation I see is the command-line help in the C file:
> 
>     printf(gettext("Usage:\n  %s --help-config [OPTION]... [NAME]\n\n"), progname);
>     printf(gettext("General Options:\n"));
>     printf(gettext("  NAME      output information about parameters matching this name\n"));
>     printf(gettext("  -g GROUP  output information about parameters matching this group\n"));
>     printf(gettext("  -l        list available parameter groups\n"));
>     printf(gettext("  -h        show this help, then exit\n"));

We don't use the ones above.

>     printf(gettext("\nOutput Options:\n"));
>     printf(gettext("  -G  do not group by category\n"));
>     printf(gettext("  -m  machine-friendly format: tab separated fields\n"));
>     printf(gettext("  -M  same as -m, but header with column names is suppressed\n"));
> 

We do use these.

> I don't see any value to most of these parameters, and the "add them in
> case they might need them" has never been our philosophy, so I don't see
> why we should add them at this point.  Can we just get minimal
> functionality and see what people ask for --- they might ask for
> something completely different from what we have spec'ed out here, and
> if they do, we will have to remove existing options to meet their needs,
> or maintain a bloat of options.  You know I have no problems adding
> options to make common tasks easier for our users, but we have no usage
> cases yet to know what they want.
> 

Our GUI tool uses only -G and -M (we may need to resort to -m soon, so we would 
like that one to be preserved as well).

The remaining ones are related to its use as a command line utility and meant to 
produce readable output.  I guess some options were indeed requested to limit 
the amount of info printed.  BTW, it was a separate utility at that time: 
pg_guc.  Aizaz was asked to transform it into a postgres --help-config option.


> What would make sense is to always output sorted by Group/Name, and see
> how that works for folks.

Please don't do it for -M/-m.  It may unnecessarily increase the response time 
of GUI tools and add to the server load.  The client can always sort or store it 
the way it wants.


>  I also didn't think the dashed lines were
> needed --- they seemed to clutter the output:
> 

This seems to be a question of personal preference.  But as I said, we only use 
the -M/-m output in our tool.

>     
>     ------------------------------------------------------------
>     Name:          preload_libraries
>     Context:       postmaster
>     Group:         Resource Usage / Kernel Resources
>     Type:          string
>     Default value:
>     Description:   shared libraries to preload into server
>     
>     ------------------------------------------------------------
>     Name:          fsync
>     Context:       sighup
>     Group:         Write-Ahead Log / Settings
>     Type:          Boolean
>     Default value: true
>     Description:   force synchronization of updates to disk
>     The server will use the fsync() system call in several places to make sure that updates are physically written to
disk.This insures that a database cluster will recover to a consistent state after an operating system or hardware
crash.
>     ------------------------------------------------------------
> 
> vs.
> 
>     
>     Name:          preload_libraries
>     Context:       postmaster
>     Group:         Resource Usage / Kernel Resources
>     Type:          string
>     Default value:
>     Description:   shared libraries to preload into server
>     
>     Name:          fsync
>     Context:       sighup
>     Group:         Write-Ahead Log / Settings
>     Type:          Boolean
>     Default value: true
>     Description:   force synchronization of updates to disk
>     The server will use the fsync() system call in several places to make sure that updates are physically written to
disk.This insures that a database cluster will recover to a consistent state after an operating system or hardware
crash.
> 
> An output that uses --help-config, and takes no flags seems like the way
> to go at this point.  If people want specific entries, they can page
> through them with less, or use a tool to extract them from the text file
> --- the output is in a very clear format.
> 

Parsing human-readable output is not very good for the tools though.  Too hard 
to parse and more subject to change.  I don't mind much what happens to the 
human-readable output, but I would need the -M/-m (with -G, separate or 
automatically assumed) to be preserved.

> I would also indent the text description (last line) to line up with the
> other data fields.
> 

That sounds like a good idea for improvement.  I don't see why it can't be done 
as an enhancement patch any time in the future.  Again, please do not change the 
-M/-m output.  Formatting will be done by the proper window widgets in that case 
and can vary with the situation.  An unchanged description string is important.


Regards to all,
Fernando

-- 
Fernando Nasser
Red Hat - Toronto                       E-Mail:  fnasser@redhat.com
2323 Yonge Street, Suite #300
Toronto, Ontario   M4P 2C9



Re: postgres --help-config

From
Alvaro Herrera
Date:
On Tue, Oct 14, 2003 at 11:34:14AM -0400, Fernando Nasser wrote:

Unrelated question,

> And we developed a very nice tool that depends on this feature
> confident that we could count on it.

Is this tool going to be released somehow?

-- 
Alvaro Herrera (<alvherre[a]dcc.uchile.cl>)
"I dream about dreams about dreams", sang the nightingale
under the pale moon (Sandman)


Re: postgres --help-config

From
Tom Lane
Date:
Alvaro Herrera <alvherre@dcc.uchile.cl> writes:
> On Tue, Oct 14, 2003 at 11:34:14AM -0400, Fernando Nasser wrote:
>> And we developed a very nice tool that depends on this feature
>> confident that we could count on it.

> Is this tool going to be released somehow?

Certainly.  Keep an eye on http://sources.redhat.com/rhdb/

I'm not sure what the release schedule is for that particular tool,
but it's soon.
        regards, tom lane


Re: postgres --help-config

From
Bruce Momjian
Date:
Fernando Nasser wrote:
> Bruce,
> 
> Before I comment on your suggestions, I would like to mention that many of the 
> things below were added on request by the few people who cared to comment on it. 
>   Aizaz spent most of his time changing here and there to accommodate these 
> requests.  Anyway, we know we can't satisfy all, but I wish people would be more 
> timely when criticizing things.  Aizaz is away until May and left thinking 
> everything was under control.  And we developed a very nice tool that depends on 
> this feature confident that we could count on it.

I understand this is not ideal timing.  However, open source is
certainly very fluid and it is hard when someone adds something and then
isn't available for later adjustments.

I knew you were adding --help-config, but I didn't realize the extent of
the "features".  The commit message is:
revision 1.1date: 2003/07/04 16:41:21;  author: tgl;  state: Exp;Add --help-config facility to dump information about
GUCparameterswithout needing a running backend.  Reorder postgresql.conf.sampleto match new layout of runtime.sgml.
Thiscommit re-adds work lostin Wednesday's crash.
 

which I thought was a single option, which we all knew was needed, not 
six additional options for output format.  Also, with no documention, or
a posted list of the flags you wanted to add (at least I never saw it),
it was easy to miss.

Imagine SRA wanted some features added to work better with their admin
tool --- if all the companies did that, PostgreSQL could become a
bloated mess.

> Bruce Momjian wrote:> Tom Lane wrote:
> > 
> > First, the default output should have the sorted field first.  It
> > appears the default is to sort by context:
> > 
> >     postgres --help-config
> > 
> > That should be the first printed field.  However, I see you can sort by
> > Group, so maybe group should always be first --- that seems most
> > logical.
> > 
> 
> Whatever you do to the human-readable output, please don't change the -M/-m 
> format.  It makes it harder to write code to parse these things if the fields 
> keep changing positions.
> 
> Someone is supposed to write an utility to create the sample postgresql.conf 
> file from the output as well.  I believe this tool would use it without the -G 
> so that is why we have the -G option. Also, it was deemed better for the user 
> readable output to have it grouped (it is easier to check with the documentation 
> as well when it is being reviewed).

We don't normally add things until someone is ready to do the actual
coding --- only then do we know what they will really want.

> > The documentation I see is the command-line help in the C file:
> > 
> >     printf(gettext("Usage:\n  %s --help-config [OPTION]... [NAME]\n\n"), progname);
> >     printf(gettext("General Options:\n"));
> >     printf(gettext("  NAME      output information about parameters matching this name\n"));
> >     printf(gettext("  -g GROUP  output information about parameters matching this group\n"));
> >     printf(gettext("  -l        list available parameter groups\n"));
> >     printf(gettext("  -h        show this help, then exit\n"));
> 
> We don't use the ones above.
> 
> >     printf(gettext("\nOutput Options:\n"));
> >     printf(gettext("  -G  do not group by category\n"));
> >     printf(gettext("  -m  machine-friendly format: tab separated fields\n"));
> >     printf(gettext("  -M  same as -m, but header with column names is suppressed\n"));
> > 
> 
> We do use these.
> 
> > I don't see any value to most of these parameters, and the "add them in
> > case they might need them" has never been our philosophy, so I don't see
> > why we should add them at this point.  Can we just get minimal
> > functionality and see what people ask for --- they might ask for
> > something completely different from what we have spec'ed out here, and
> > if they do, we will have to remove existing options to meet their needs,
> > or maintain a bloat of options.  You know I have no problems adding
> > options to make common tasks easier for our users, but we have no usage
> > cases yet to know what they want.
> > 
> 
> Our GUI tool uses only -G and -M (we may need to resort to -m soon, so we would 
> like that one to be preserved as well).
> 
> The remaining ones are related to its use as a command line utility and meant to 
> produce readable output.  I guess some options were indeed requested to limit 
> the amount of info printed.  BTW, it was a separate utility at that time: 
> pg_guc.  Aizaz was asked to transform it into a postgres --help-config option.

I think --help-config needs to be a postgres flag, but the output format
flags should be in a separate utility, perhaps not one we ship with
PostgreSQL. I would not have a problem with a separate tool, perhaps in
the src/tools directory, that would parse the output into all sorts of
formats.  I am just learning Perl, but I bet I could do it.  The
advantage of a src/tools script is that it is isolated, doesn't have to
be documented as thoroughly, and can even be adjusted from release to
release.  

> > What would make sense is to always output sorted by Group/Name, and see
> > how that works for folks.
> 
> Please don't do it for -M/-m.  It may unnecessarily increase the response time 
> of GUI tools and add to the server load.  The client can always sort or store it 
> the way it wants.

You are worried about response time on a tool that parses output?  Seems
it would be much clearer to run postgres --help-config, load that into a
perl array, then do the sorting and output as desired.

> >  I also didn't think the dashed lines were
> > needed --- they seemed to clutter the output:
> > 
> 
> This seems to be a question of personal preference.  But as I said, we only use 
> the -M/-m output in our tool.

> > An output that uses --help-config, and takes no flags seems like the way
> > to go at this point.  If people want specific entries, they can page
> > through them with less, or use a tool to extract them from the text file
> > --- the output is in a very clear format.
> > 
> 
> Parsing human-readable output is not very good for the tools though.  Too hard 
> to parse and more subject to change.  I don't mind much what happens to the 
> human-readable output, but I would need the -M/-m (with -G, separate or 
> automatically assumed) to be preserved.
> 
> > I would also indent the text description (last line) to line up with the
> > other data fields.
> > 
> 
> That sounds like a good idea for improvement.  I don't see why it can't be done 
> as an enhancement patch any time in the future.  Again, please do not change the 
> -M/-m output.  Formatting will be done by the proper window widgets in that case 
> and can vary with the situation.  An unchanged description string is important.

Let me be clear on this --- your tools is not part of the PostgreSQL
community.  We are not required to allow any of this functionality
unless the community decides they want it.  The major argument for
keeping it, in my mind, is to be helpful to Red Hat.

My current idea is to keep --help-config as readable output, add
--help-config-raw as machine-readable output, document those, and remove
all the additional flags.

--  Bruce Momjian                        |  http://candle.pha.pa.us pgman@candle.pha.pa.us               |  (610)
359-1001+  If your life is a hard drive,     |  13 Roberts Road +  Christ can be your backup.        |  Newtown Square,
Pennsylvania19073
 


Re: postgres --help-config

From
Jon Jensen
Date:
On Tue, 14 Oct 2003, Bruce Momjian wrote:

> I knew you were adding --help-config, but I didn't realize the extent of
> the "features".  The commit message is:
> 
>     revision 1.1
>     date: 2003/07/04 16:41:21;  author: tgl;  state: Exp;
>     Add --help-config facility to dump information about GUC parameters
>     without needing a running backend.  Reorder postgresql.conf.sample
>     to match new layout of runtime.sgml.  This commit re-adds work lost
>     in Wednesday's crash.
> 
> which I thought was a single option, which we all knew was needed, not 
> six additional options for output format.  Also, with no documention, or
> a posted list of the flags you wanted to add (at least I never saw it),
> it was easy to miss.

Is there a mailing list somewhere that all the CVS commits get sent to?  
Other projects I've worked on have such a list, and each commit message is
followed by a complete diff (usually with -u for readability) so even
non-committers can do a code read right then and there while the changes
are still fresh in the author's mind and can be discussed in detail.

If such a list already exists, where do I subscribe? If not, don't you
think it would be helpful in spreading around fuller knowledge of changes
to the codebase?

Jon


Re: postgres --help-config

From
Alvaro Herrera Munoz
Date:
On Tue, Oct 14, 2003 at 07:52:55PM +0000, Jon Jensen wrote:

> Is there a mailing list somewhere that all the CVS commits get sent to?  

Yes, pgsql-committers.

> Other projects I've worked on have such a list, and each commit message is
> followed by a complete diff (usually with -u for readability) so even
> non-committers can do a code read right then and there while the changes
> are still fresh in the author's mind and can be discussed in detail.

I wouldn't want the whole diff on the mail, but a link to the relevant
diffs in cvsweb would be most useful (one for each changed file -- not ideal,
but much better than nothing).  You're not the first one to suggest it ...

-- 
Alvaro Herrera (<alvherre[@]dcc.uchile.cl>)
"El destino baraja y nosotros jugamos" (A. Schopenhauer)


Re: postgres --help-config

From
Neil Conway
Date:
On Tue, 2003-10-14 at 15:57, Alvaro Herrera Munoz wrote:
> On Tue, Oct 14, 2003 at 07:52:55PM +0000, Jon Jensen wrote:
> > Other projects I've worked on have such a list, and each commit message is
> > followed by a complete diff (usually with -u for readability) so even
> > non-committers can do a code read right then and there while the changes
> > are still fresh in the author's mind and can be discussed in detail.
> 
> I wouldn't want the whole diff on the mail, but a link to the relevant
> diffs in cvsweb would be most useful (one for each changed file -- not ideal,
> but much better than nothing).  You're not the first one to suggest it ...

I agree, it would be very useful. Marc, would it be possible to set this
up?

-Neil




Re: postgres --help-config

From
Rod Taylor
Date:
> > I wouldn't want the whole diff on the mail, but a link to the relevant
> > diffs in cvsweb would be most useful (one for each changed file -- not ideal,
> > but much better than nothing).  You're not the first one to suggest it ...
>
> I agree, it would be very useful. Marc, would it be possible to set this
> up?

I volunteer to provide a patch (after 7.4 release) to CVSMODULES to do
this for emails and the $PostgreSQL$ bit.

It will be based upon the freely available FreeBSD code line.

Re: postgres --help-config

From
Jon Jensen
Date:
On Tue, 14 Oct 2003, Rod Taylor wrote:

> > > I wouldn't want the whole diff on the mail, but a link to the relevant
> > > diffs in cvsweb would be most useful (one for each changed file -- not ideal,
> > > but much better than nothing).  You're not the first one to suggest it ...
> > 
> > I agree, it would be very useful. Marc, would it be possible to set this
> > up?
> 
> I volunteer to provide a patch (after 7.4 release) to CVSMODULES to do
> this for emails and the $PostgreSQL$ bit.
> 
> It will be based upon the freely available FreeBSD code line.

FreeBSD's CVS scripts are the ones I've used too, and they work well. 

Perhaps it would make sense to have a separate mailing list so people who 
only want to see commit notices and not full diffs will be happy? 
Personally I don't find commit notices without diffs very useful -- if 
forced to choose, I'd rather have diffs without notices. :) But I can 
understand people not wanting to deal with the huge increase in message 
sizes if they're on a slow dial-up link or whatever.

Jon


Re: postgres --help-config

From
Peter Eisentraut
Date:
Bruce Momjian writes:

> Let me be clear on this --- your tools is not part of the PostgreSQL
> community.  We are not required to allow any of this functionality
> unless the community decides they want it.  The major argument for
> keeping it, in my mind, is to be helpful to Red Hat.
>
> My current idea is to keep --help-config as readable output, add
> --help-config-raw as machine-readable output, document those, and remove
> all the additional flags.

I'm beginning to think that we should scrap it and start with a real
design for 7.5.  I know that's radical, but I don't think we're going to
arrive at anything that anyone's going to like by the time we want to
release.

-- 
Peter Eisentraut   peter_e@gmx.net



Re: postgres --help-config

From
Bruce Momjian
Date:
Peter Eisentraut wrote:
> Bruce Momjian writes:
> 
> > Let me be clear on this --- your tools is not part of the PostgreSQL
> > community.  We are not required to allow any of this functionality
> > unless the community decides they want it.  The major argument for
> > keeping it, in my mind, is to be helpful to Red Hat.
> >
> > My current idea is to keep --help-config as readable output, add
> > --help-config-raw as machine-readable output, document those, and remove
> > all the additional flags.
> 
> I'm beginning to think that we should scrap it and start with a real
> design for 7.5.  I know that's radical, but I don't think we're going to
> arrive at anything that anyone's going to like by the time we want to
> release.

The problem is how that affects Red Hat.  What do they do with their
tool?  I was hoping we could get a minimal setup for them to access
those variables so they could move forward.

Let me add I know these admin tools are very popular with support
companies.  I know SRA has an admin tool that can control
postgresql.conf variables.  My guess is that they did it by hacking
their version of PostgreSQL.  

Looks like they have new URL showing their Win32 and enhanced PostgreSQL
products (English auto-translation):
http://www.excite.co.jp/world/url/body?wb_url=http%3A%2F%2Fpowergres.sra.co.jp%2F&wb_lp=JAEN&wb_dis=2

--  Bruce Momjian                        |  http://candle.pha.pa.us pgman@candle.pha.pa.us               |  (610)
359-1001+  If your life is a hard drive,     |  13 Roberts Road +  Christ can be your backup.        |  Newtown Square,
Pennsylvania19073
 


Re: postgres --help-config

From
Tom Lane
Date:
Bruce Momjian <pgman@candle.pha.pa.us> writes:
> Peter Eisentraut wrote:
>> I'm beginning to think that we should scrap it and start with a real
>> design for 7.5.  I know that's radical, but I don't think we're going to
>> arrive at anything that anyone's going to like by the time we want to
>> release.

> The problem is how that affects Red Hat.  What do they do with their
> tool?

I believe said tool is within a couple days of code freeze for initial
release, in fact.  We could probably still cope with a change in the
spelling of the switches, but redesigning the output format or removing
the functionality altogether would be a very nasty surprise.

> > Let me be clear on this --- your tools is not part of the PostgreSQL
> > community.  We are not required to allow any of this functionality
> > unless the community decides they want it.

I'm really having a hard time responding to this line of argument
politely.  Where were all these complaints when the patch was proposed
and accepted?  If there's not time now to redesign the feature to your
liking, it is *NOT* Red Hat's fault, it is *YOURS*.  Yanking the rug out
from under someone else's project just because you didn't review the
patch adequately at the time is not my idea of how a community should act.
        regards, tom lane


Re: postgres --help-config

From
Bruce Momjian
Date:
Tom Lane wrote:
> Bruce Momjian <pgman@candle.pha.pa.us> writes:
> > Peter Eisentraut wrote:
> >> I'm beginning to think that we should scrap it and start with a real
> >> design for 7.5.  I know that's radical, but I don't think we're going to
> >> arrive at anything that anyone's going to like by the time we want to
> >> release.
> 
> > The problem is how that affects Red Hat.  What do they do with their
> > tool?
> 
> I believe said tool is within a couple days of code freeze for initial
> release, in fact.  We could probably still cope with a change in the
> spelling of the switches, but redesigning the output format or removing
> the functionality altogether would be a very nasty surprise.
> 
> > > Let me be clear on this --- your tools is not part of the PostgreSQL
> > > community.  We are not required to allow any of this functionality
> > > unless the community decides they want it.
> 
> I'm really having a hard time responding to this line of argument
> politely.  Where were all these complaints when the patch was proposed
> and accepted?  If there's not time now to redesign the feature to your
> liking, it is *NOT* Red Hat's fault, it is *YOURS*.  Yanking the rug out
> from under someone else's project just because you didn't review the
> patch adequately at the time is not my idea of how a community should act.

I thought you might have an emotional reaction to this issue.

I did not review these changes thoroughly because:
o There was no proposal on the switches and their usage.o The commit message didn't mention any switches other than
--help-config.oThere are no docs to show the new flags.o You were handling it, and I trusted your style, so I didn't
seea reason to study it more thoroughly.
 

Let's imagine how this would have worked for an outside project/company:
o Project leader comes to us and says they want to make a PostgreSQL  admin tool.o They explain their needs and we
agreeon how to implement it.o We implement the feature as discussed.
 

Would we have agreed to adding all those flags?  I don't think so.  We
would have given them a clean output, and asked them to handle the
functionality in their code, which is probably the correct approach.

This procedure is in our developer's FAQ:
   The usual process for source additions is:
   o Review the TODO list.   o Discuss hackers the desirability of the fix/feature.   o How should it behave in complex
circumstances?  o How should it be implemented?   o Submit the patch to the patches list.   o Answer email questions.
oWait for the patch to be applied.
 

Now, we have Red Hat having you add a patch on July 4 (posted for review
June 30), very near feature freeze, but it meets a discussed need
(--help-config), so it goes in.  I only learned about it when Peter saw
the C code handling the new flags and asked questions about it.  I do
see the patch submitted, with clear illustration of the flags:
http://archives.postgresql.org/pgsql-patches/2003-06/msg00420.php

I guess I thought those flags were for Red Hat's tool or a separate
utility, but it clearly states it is part of the postgres binary, so
that was my fault.

It looks like this all became visible on September 29:

http://groups.google.com/groups?hl=en&lr=&ie=UTF-8&threadm=29402.1065021420%40sss.pgh.pa.us&rnum=2&prev=/groups%3Fq%3Dhelp-config%2Bgroup:comp.databases.postgresql.*%26hl%3Den%26lr%3D%26ie%3DUTF-8%26group%3Dcomp.databases.postgresql.*%26selm%3D29402.1065021420%2540sss.pgh.pa.us%26rnum%3D2

I think I am agreeing with Peter's comment in that email thread:I'm quite unhappy about the --help-config option.  It
wasdevelopedwithout discussion, it was installed hastily, we don't have anyinformation about that interactive
configurationapplication it's supposedto target, it's not documented, it's full of unfinished business, itcertainly
doesn'tmake the code easier to maintain because all thedocumenation is duplicated, but not one-to-one.  At this point,
Iwouldn'tspend a lot of time trying to make sense of it.  We can revisit it againin the next release and investigate
howwe can eliminate the duplicationof effort between the documentation and the code.
 

We certainly want to keep Red Hat happy.  Will Red Hat be upset if we
leave it unchanged for 7.4.X and rip this out and redo it in 7.5?

--  Bruce Momjian                        |  http://candle.pha.pa.us pgman@candle.pha.pa.us               |  (610)
359-1001+  If your life is a hard drive,     |  13 Roberts Road +  Christ can be your backup.        |  Newtown Square,
Pennsylvania19073
 


Re: postgres --help-config

From
Tom Lane
Date:
Bruce Momjian <pgman@candle.pha.pa.us> writes:
> ... Will Red Hat be upset if we
> leave it unchanged for 7.4.X and rip this out and redo it in 7.5?

It'd be better if we could get it right the first time, with the
understanding that the output format is not very negotiable at this
late hour.  But as best I can tell, most of the unhappiness is with the
design of the switch set, which is not something I want to defend in
detail.  There's a lot there that isn't needed for the RHDB tool as I
understand it, and I think that altering the switches used to get the
output that the tool does need would still be a feasible change from the
tool's point of view.

I would be in favor of simplifying the supported switch set to the
minimum needed by Red Hat's tool (the equivalent of -G -M if I
understood Fernando correctly), and re-adding complexity in future
when and if it's shown to be needed.  But we need to make a decision
about this now.  Preferably yesterday.
        regards, tom lane


Re: postgres --help-config

From
Peter Eisentraut
Date:
Bruce Momjian writes:

> The problem is how that affects Red Hat.  What do they do with their
> tool?

They could use the prototype version of this feature that implemented a
separate program (pg_guc) that provided this information.  That way they
can generate any output they want for as long as they want without
affecting anyone.

-- 
Peter Eisentraut   peter_e@gmx.net



Re: postgres --help-config

From
Peter Eisentraut
Date:
Tom Lane writes:

> It'd be better if we could get it right the first time, with the
> understanding that the output format is not very negotiable at this
> late hour.  But as best I can tell, most of the unhappiness is with the
> design of the switch set, which is not something I want to defend in
> detail.  There's a lot there that isn't needed for the RHDB tool as I
> understand it, and I think that altering the switches used to get the
> output that the tool does need would still be a feasible change from the
> tool's point of view.

I have some more questions:

- When the set of GUC properties (when to set, how to set, etc.) change, what is the upgrade path?  Remember that we
changethose a lot.
 

- Who is going to maintain the descriptions in this very special "GNU trick" format?  I can happily agree if we had a
shortdescription that is shown in an overview list, and an long description that is shown when the option is opened up
inits own window, but I don't agree with with the current format.  At least not in the way it was explained to me,
maybeI'm misunderstanding.
 

> I would be in favor of simplifying the supported switch set to the
> minimum needed by Red Hat's tool (the equivalent of -G -M if I
> understood Fernando correctly), and re-adding complexity in future
> when and if it's shown to be needed.  But we need to make a decision
> about this now.  Preferably yesterday.

I propose we rip out everything except --help-config -m that shows the
information in the "machine-readable" tab separated format without
headers.  If someone can answer the two questions above.

-- 
Peter Eisentraut   peter_e@gmx.net



Re: postgres --help-config

From
Bruce Momjian
Date:
Tom Lane wrote:
> Bruce Momjian <pgman@candle.pha.pa.us> writes:
> > ... Will Red Hat be upset if we
> > leave it unchanged for 7.4.X and rip this out and redo it in 7.5?
> 
> It'd be better if we could get it right the first time, with the
> understanding that the output format is not very negotiable at this
> late hour.  But as best I can tell, most of the unhappiness is with the
> design of the switch set, which is not something I want to defend in
> detail.  There's a lot there that isn't needed for the RHDB tool as I
> understand it, and I think that altering the switches used to get the
> output that the tool does need would still be a feasible change from the
> tool's point of view.
> 
> I would be in favor of simplifying the supported switch set to the
> minimum needed by Red Hat's tool (the equivalent of -G -M if I
> understood Fernando correctly), and re-adding complexity in future
> when and if it's shown to be needed.  But we need to make a decision
> about this now.  Preferably yesterday.

I understand we want to get something that _isn't_ going to change after
7.4.  That's why I proposed a simple --help-config in user-readable
format (might be improved in the future), and a --help-config-raw in tab
format, without headers.  Seems the tool can use the tab format to do
whatever it wants, including loading it into a C structure and running
the existing help_config.c code over it.   I also can't imagine the raw
format every changing, because of course, it is "raw".  I think everyone
agrees we need a user-readable and machine-readable output for this.  As
I mentioned earlier, SRA has a tool that does this too, so it must be a
pretty common need.

My guess is that every tool is going to want to get at the data in a
different way, so we are better off just passing the data in a neutral
format and letting the tool manipulate the data, rather than trying to
guess what features the tool will need.

One thing that seems very strange about the current API are flags that
have meaning only when --help-config becomes before it, as with -G and
-M.  I have never seen that before, and I don't know how we would even
document that.  We do have pg_ctl that has different flags for different
modes, but a word is required at the beginning, not a flag.

I guess iff someone needs raw with headers in the future, I guess we
could add --help-config-raw-headers.

--  Bruce Momjian                        |  http://candle.pha.pa.us pgman@candle.pha.pa.us               |  (610)
359-1001+  If your life is a hard drive,     |  13 Roberts Road +  Christ can be your backup.        |  Newtown Square,
Pennsylvania19073
 


Re: postgres --help-config

From
Bruce Momjian
Date:
Peter Eisentraut wrote:
> Tom Lane writes:
> 
> > It'd be better if we could get it right the first time, with the
> > understanding that the output format is not very negotiable at this
> > late hour.  But as best I can tell, most of the unhappiness is with the
> > design of the switch set, which is not something I want to defend in
> > detail.  There's a lot there that isn't needed for the RHDB tool as I
> > understand it, and I think that altering the switches used to get the
> > output that the tool does need would still be a feasible change from the
> > tool's point of view.
> 
> I have some more questions:
> 
> - When the set of GUC properties (when to set, how to set, etc.) change,
>   what is the upgrade path?  Remember that we change those a lot.

You mean when we add another member the GUC structure?  I assume the
tool is first going to have to test for the PostgreSQL version, and
handle each version slightly differently --- I don't see another way. 
Perhaps that's what the 'headings' flag was for, but I don't think that
really helps much --- there has to be code to understand what that new
column means.

> - Who is going to maintain the descriptions in this very special "GNU
>   trick" format?  I can happily agree if we had a short description that
>   is shown in an overview list, and an long description that is shown when
>   the option is opened up in its own window, but I don't agree with with
>   the current format.  At least not in the way it was explained to me,
>   maybe I'm misunderstanding.

Are you talking about the descriptions in the guc.c file that are part
of the GUC structures?  I think we are heading in a direction where we
should be pulling descriptions out of SGML like we do with psql help,
and using that to load the GUC structures with descriptions.  I don't
see another long-term solution, do you?

> > I would be in favor of simplifying the supported switch set to the
> > minimum needed by Red Hat's tool (the equivalent of -G -M if I
> > understood Fernando correctly), and re-adding complexity in future
> > when and if it's shown to be needed.  But we need to make a decision
> > about this now.  Preferably yesterday.
> 
> I propose we rip out everything except --help-config -m that shows the
> information in the "machine-readable" tab separated format without
> headers.  If someone can answer the two questions above.

I just proposed that as --help-config-raw.  I don't think we want to
head in the direction of having flags like -m be useful only if
preceeded by a --help-config flag --- it is too confusing.  I think
--help-config and --help-config-raw is all we will ever need.

--  Bruce Momjian                        |  http://candle.pha.pa.us pgman@candle.pha.pa.us               |  (610)
359-1001+  If your life is a hard drive,     |  13 Roberts Road +  Christ can be your backup.        |  Newtown Square,
Pennsylvania19073
 


Re: postgres --help-config

From
Bruce Momjian
Date:
Tom Lane wrote:
> Bruce Momjian <pgman@candle.pha.pa.us> writes:
> > ... Will Red Hat be upset if we
> > leave it unchanged for 7.4.X and rip this out and redo it in 7.5?
> 
> It'd be better if we could get it right the first time, with the
> understanding that the output format is not very negotiable at this
> late hour.  But as best I can tell, most of the unhappiness is with the
> design of the switch set, which is not something I want to defend in
> detail.  There's a lot there that isn't needed for the RHDB tool as I
> understand it, and I think that altering the switches used to get the
> output that the tool does need would still be a feasible change from the
> tool's point of view.
> 
> I would be in favor of simplifying the supported switch set to the
> minimum needed by Red Hat's tool (the equivalent of -G -M if I
> understood Fernando correctly), and re-adding complexity in future
> when and if it's shown to be needed.  But we need to make a decision
> about this now.  Preferably yesterday.

Oh, the raw output format should follow the COPY format output, meaning
literal newlines are \n and literal tabs are \<tab>, and double literal
backslash.  I am mentioning this now so we will not have to modify this
output format in the future in case we need literal tab/newlines.

--  Bruce Momjian                        |  http://candle.pha.pa.us pgman@candle.pha.pa.us               |  (610)
359-1001+  If your life is a hard drive,     |  13 Roberts Road +  Christ can be your backup.        |  Newtown Square,
Pennsylvania19073
 


Re: postgres --help-config

From
Andrew Dunstan
Date:
Bruce Momjian wrote:

>>I propose we rip out everything except --help-config -m that shows the
>>information in the "machine-readable" tab separated format without
>>headers.  If someone can answer the two questions above.
>>    
>>
>
>I just proposed that as --help-config-raw.  I don't think we want to
>head in the direction of having flags like -m be useful only if
>preceeded by a --help-config flag --- it is too confusing.  I think
>--help-config and --help-config-raw is all we will ever need.
>
>  
>
Or you could allow --help-config to take an optional argument of "raw".

I agree that having flag interdependencies like the original is confusing.

Just a thought.

cheers

andrew



Re: postgres --help-config

From
Tom Lane
Date:
Bruce Momjian <pgman@candle.pha.pa.us> writes:
> One thing that seems very strange about the current API are flags that
> have meaning only when --help-config becomes before it, as with -G and
> -M.  I have never seen that before,

postgres -boot does exactly that, and the new code was modeled on it.
Which doesn't make it good design, maybe, but you can hardly claim
that there's no precedent.

We had also considered choosing a different executable name (the
postmaster-vs-postgres trick).  But on platforms without symlinks,
like Windows, that would mean an extra whole copy of the backend
in the installed system, which seemed a bit much just to avoid some
ugliness in the switch set...
        regards, tom lane


Re: postgres --help-config

From
Tom Lane
Date:
Bruce Momjian <pgman@candle.pha.pa.us> writes:
> I understand we want to get something that _isn't_ going to change after
> 7.4.  That's why I proposed a simple --help-config in user-readable
> format (might be improved in the future), and a --help-config-raw in tab
> format, without headers.

Actually, I think the point Peter's been making is that it's not clear
we need a "user-readable" output format at all.  The variant you are
calling --help-config-raw is the only one that needs to be supported in
7.4, and anything else should (arguably) be left off so that it doesn't
constrain a future redesign.
        regards, tom lane


Re: postgres --help-config

From
Tom Lane
Date:
Peter Eisentraut <peter_e@gmx.net> writes:
> - When the set of GUC properties (when to set, how to set, etc.) change,
>   what is the upgrade path?  Remember that we change those a lot.

Well, when we add another PGC_ category, that will mean another possible
output value in the column representing same.  That doesn't bother me
particularly.  The other flag bits that we have aren't currently
reflected in the help-config output at all, so changing them doesn't
affect it.

> - Who is going to maintain the descriptions in this very special "GNU
>   trick" format?

What's special about it?  I now understand that I'd misdescribed it, and
that the fields ought to be named something like "desc" and "extra_desc"
rather than "short_desc" and "long_desc".  But I don't see anything
wrong with the concept.  The short description is also the first
sentence of the long description; what's unreasonable about that?

> I propose we rip out everything except --help-config -m that shows the
> information in the "machine-readable" tab separated format without
> headers.  If someone can answer the two questions above.

Actually I think -M -G corresponds to that set of choices.  Are we
converging on an agreement that we only need that functionality for now?
If so, what switch shall be used to get it?
        regards, tom lane


Re: postgres --help-config

From
Fernando Nasser
Date:
Tom Lane wrote:
> 
> Actually, I think the point Peter's been making is that it's not clear
> we need a "user-readable" output format at all.  The variant you are
> calling --help-config-raw is the only one that needs to be supported in
> 7.4, and anything else should (arguably) be left off so that it doesn't
> constrain a future redesign.
> 

I agree.  We can revive the pg_guc utility to obtain the raw input using 
'postgres --help-config' and format it the way you want and give it all 
the switches that people may want.

I just wonder if having a help-like option without human-readable output
is OK.  We can always document that it is for machine consumption, of 
course.


-- 
Fernando Nasser
Red Hat Canada Ltd.                     E-Mail:  fnasser@redhat.com
2323 Yonge Street, Suite #300
Toronto, Ontario   M4P 2C9



Re: postgres --help-config

From
Fernando Nasser
Date:
Bruce Momjian wrote:
> 
(...)
> I guess iff someone needs raw with headers in the future, I guess we
> could add --help-config-raw-headers.
> 

I don't mind if you make it always with the headers.  We can easily 
strip the first line when reading the file and people can easily strip 
it piping the output through a filter before sorting it etc.

I am thinking that the headers would allow a output formatting utility 
to do it in a way that is independent of the version, and avoid having 
to run "pg_config --version" as well.  As the values are all strings it 
can blindly create a column for every header.  The only fields that the 
program need to know about (like name and group) are not likely to change.

No big deal though.

-- 
Fernando Nasser
Red Hat Canada Ltd.                     E-Mail:  fnasser@redhat.com
2323 Yonge Street, Suite #300
Toronto, Ontario   M4P 2C9



Re: postgres --help-config

From
Tom Lane
Date:
Bruce Momjian <pgman@candle.pha.pa.us> writes:
> Are you talking about the descriptions in the guc.c file that are part
> of the GUC structures?  I think we are heading in a direction where we
> should be pulling descriptions out of SGML like we do with psql help,
> and using that to load the GUC structures with descriptions.

Peter had suggested generating the docs and the GUC table from a common
source file, and I think that is the way to go, but it's obviously not
getting done for 7.4.
        regards, tom lane


Re: postgres --help-config

From
Bruce Momjian
Date:
Tom Lane wrote:
> Bruce Momjian <pgman@candle.pha.pa.us> writes:
> > One thing that seems very strange about the current API are flags that
> > have meaning only when --help-config becomes before it, as with -G and
> > -M.  I have never seen that before,
> 
> postgres -boot does exactly that, and the new code was modeled on it.
> Which doesn't make it good design, maybe, but you can hardly claim
> that there's no precedent.

However, -boot isn't documented because it is only for internal use.
If it was for general use, I doubt it would still use that API.

> We had also considered choosing a different executable name (the
> postmaster-vs-postgres trick).  But on platforms without symlinks,
> like Windows, that would mean an extra whole copy of the backend
> in the installed system, which seemed a bit much just to avoid some
> ugliness in the switch set...

Agreed.

--  Bruce Momjian                        |  http://candle.pha.pa.us pgman@candle.pha.pa.us               |  (610)
359-1001+  If your life is a hard drive,     |  13 Roberts Road +  Christ can be your backup.        |  Newtown Square,
Pennsylvania19073
 


Re: postgres --help-config

From
Bruce Momjian
Date:
Tom Lane wrote:
> Bruce Momjian <pgman@candle.pha.pa.us> writes:
> > I understand we want to get something that _isn't_ going to change after
> > 7.4.  That's why I proposed a simple --help-config in user-readable
> > format (might be improved in the future), and a --help-config-raw in tab
> > format, without headers.
> 
> Actually, I think the point Peter's been making is that it's not clear
> we need a "user-readable" output format at all.  The variant you are
> calling --help-config-raw is the only one that needs to be supported in
> 7.4, and anything else should (arguably) be left off so that it doesn't
> constrain a future redesign.

Agreed.  No one is asking for user-readable output, and if we output in
COPY format, we can just publish the schema and they can load it into
their favorate database.

--  Bruce Momjian                        |  http://candle.pha.pa.us pgman@candle.pha.pa.us               |  (610)
359-1001+  If your life is a hard drive,     |  13 Roberts Road +  Christ can be your backup.        |  Newtown Square,
Pennsylvania19073
 


Re: postgres --help-config

From
Bruce Momjian
Date:
Fernando Nasser wrote:
> Bruce Momjian wrote:
> > 
> (...)
> > I guess iff someone needs raw with headers in the future, I guess we
> > could add --help-config-raw-headers.
> > 
> 
> I don't mind if you make it always with the headers.  We can easily 
> strip the first line when reading the file and people can easily strip 
> it piping the output through a filter before sorting it etc.

I think we are better off without headers.  COPY doesn't have headers,
so if we are using COPY output format, headers don't make sense --- any
my guess is that you will have to check --version anyway for special
handling, so having the headings isn't going to be a huge help.  If we
want headings, I suggest we have a special option that dumps out _only_
the headings.  In fact, it might be nicer to have it dump out the CREATE
TABLE needed to load the raw output.

> I am thinking that the headers would allow a output formatting utility 
> to do it in a way that is independent of the version, and avoid having 
> to run "pg_config --version" as well.  As the values are all strings it 
> can blindly create a column for every header.  The only fields that the 
> program need to know about (like name and group) are not likely to change.

At this point, we should probably just do what is needed, and revisit
for 7.5 --- straight COPY output would probably do the trick.

Now, for a name.  I wonder if --config-copy would be OK.  It documents
it is in COPY output format, and it allows us to add a human-readable
version in the future if we ever want one.  I didn't like --help-config
because it is too easily confused with --help, which documents
command-line flags --- this really doesn't do that.

--  Bruce Momjian                        |  http://candle.pha.pa.us pgman@candle.pha.pa.us               |  (610)
359-1001+  If your life is a hard drive,     |  13 Roberts Road +  Christ can be your backup.        |  Newtown Square,
Pennsylvania19073
 


Re: postgres --help-config

From
Bruce Momjian
Date:
Bruce Momjian wrote:
> At this point, we should probably just do what is needed, and revisit
> for 7.5 --- straight COPY output would probably do the trick.
> 
> Now, for a name.  I wonder if --config-copy would be OK.  It documents
> it is in COPY output format, and it allows us to add a human-readable
> version in the future if we ever want one.  I didn't like --help-config
> because it is too easily confused with --help, which documents
> command-line flags --- this really doesn't do that.

I am now thinking maybe --config-dump would be the proper option name
--- it is really a dump of the config stuff.

--  Bruce Momjian                        |  http://candle.pha.pa.us pgman@candle.pha.pa.us               |  (610)
359-1001+  If your life is a hard drive,     |  13 Roberts Road +  Christ can be your backup.        |  Newtown Square,
Pennsylvania19073
 


Re: postgres --help-config

From
Peter Eisentraut
Date:
Tom Lane writes:

> > - Who is going to maintain the descriptions in this very special "GNU
> >   trick" format?
>
> What's special about it?  I now understand that I'd misdescribed it, and
> that the fields ought to be named something like "desc" and "extra_desc"
> rather than "short_desc" and "long_desc".  But I don't see anything
> wrong with the concept.  The short description is also the first
> sentence of the long description; what's unreasonable about that?

It constrains the writer of the description in a way he might not suspect.
For example, we have

check_function_bodies (boolean)
   This parameter is normally true. When set false, it disables   validation ...

Then the primary description would become "This parameter is normally
true."

I think there are two ways this can be resolved:

1) Leave it this way, deal with it, but then we can put everything in one
field and let the software parse out the first sentence automatically.

2) Make real separate "short" and "long" descriptions.

> > I propose we rip out everything except --help-config -m that shows the
> > information in the "machine-readable" tab separated format without
> > headers.  If someone can answer the two questions above.
>
> Actually I think -M -G corresponds to that set of choices.  Are we
> converging on an agreement that we only need that functionality for now?
> If so, what switch shall be used to get it?

I'm thinking that a completely different option name like --dump-config or
--copy-config-info is better than something that implies "help".  I would
actually like --help-config to work exactly like --help, so it displays
something like

Options:
... --sort-mem=INT    amount of memory to be used by internal sort                   operations and hash tables before
switchingto                   temporary disk files --...
 

-- 
Peter Eisentraut   peter_e@gmx.net



Re: postgres --help-config

From
Bruce Momjian
Date:
Peter Eisentraut wrote:
> > Actually I think -M -G corresponds to that set of choices.  Are we
> > converging on an agreement that we only need that functionality for now?
> > If so, what switch shall be used to get it?
> 
> I'm thinking that a completely different option name like --dump-config or
> --copy-config-info is better than something that implies "help".  I would
> actually like --help-config to work exactly like --help, so it displays
> something like
> 
> Options:
> ...
>   --sort-mem=INT    amount of memory to be used by internal sort
>                     operations and hash tables before switching to
>                     temporary disk files
>   --...

Agreed.  I like --dump-config.  Better to have the verb first.

--  Bruce Momjian                        |  http://candle.pha.pa.us pgman@candle.pha.pa.us               |  (610)
359-1001+  If your life is a hard drive,     |  13 Roberts Road +  Christ can be your backup.        |  Newtown Square,
Pennsylvania19073
 


Re: postgres --help-config

From
Tom Lane
Date:
Bruce Momjian <pgman@candle.pha.pa.us> writes:
> Agreed.  I like --dump-config.  Better to have the verb first.

My only objection to that is that "dump" suggests you will get some kind
of snapshot of current settings, which is not what this facility does.

I don't have an especially good alternative though ... "--describe-config"
is the only thought that comes to mind right away.
        regards, tom lane


Re: postgres --help-config

From
Tom Lane
Date:
Peter Eisentraut <peter_e@gmx.net> writes:
> Tom Lane writes:
>> But I don't see anything
>> wrong with the concept.  The short description is also the first
>> sentence of the long description; what's unreasonable about that?

> It constrains the writer of the description in a way he might not suspect.
> For example, we have

> check_function_bodies (boolean)
>     This parameter is normally true. When set false, it disables
>     validation ...

> Then the primary description would become "This parameter is normally
> true."

You have a point, but on the other hand, as the author of that
particular description I can feel free to criticize it.  It's generally
considered good style for the first sentence of a paragraph to convey
the basic point.  (In fact, I recall being dissatisfied with that text
when I wrote it, but I was too rushed to fix it.)  Maybe we should just
go ahead and rewrite the variable descriptions to conform to this style.

> I think there are two ways this can be resolved:
> 1) Leave it this way, deal with it, but then we can put everything in one
> field and let the software parse out the first sentence automatically.

True.

> 2) Make real separate "short" and "long" descriptions.

We'd have to break the strings freeze to do that.  How bad do you want it?
        regards, tom lane


Re: postgres --help-config

From
Bruce Momjian
Date:
Tom Lane wrote:
> Bruce Momjian <pgman@candle.pha.pa.us> writes:
> > Agreed.  I like --dump-config.  Better to have the verb first.
> 
> My only objection to that is that "dump" suggests you will get some kind
> of snapshot of current settings, which is not what this facility does.

I think people will associate dump with pg_dump, meaning "dump out the
data".  I don't think the snapshot idea will not occur to them.  Copy
has an in/out capability that doesn't match.

--  Bruce Momjian                        |  http://candle.pha.pa.us pgman@candle.pha.pa.us               |  (610)
359-1001+  If your life is a hard drive,     |  13 Roberts Road +  Christ can be your backup.        |  Newtown Square,
Pennsylvania19073
 


Re: postgres --help-config

From
Alvaro Herrera
Date:
On Wed, Oct 15, 2003 at 07:22:56PM -0400, Tom Lane wrote:
> Peter Eisentraut <peter_e@gmx.net> writes:

> > 2) Make real separate "short" and "long" descriptions.
> 
> We'd have to break the strings freeze to do that.  How bad do you want it?

It doesn't take a lot to re-translate, IMO as a translator.  It's just a
dozen or two of strings, isn't it?  The backend has some 1800 messages,
several of which are a lot longer and more difficult to translate.

-- 
Alvaro Herrera (<alvherre[a]dcc.uchile.cl>)
"La naturaleza, tan frágil, tan expuesta a la muerte... y tan viva"


Re: postgres --help-config

From
Thomas Swan
Date:
Bruce Momjian wrote:

>Tom Lane wrote:
>  
>
>>Bruce Momjian <pgman@candle.pha.pa.us> writes:
>>    
>>
>>>Agreed.  I like --dump-config.  Better to have the verb first.
>>>      
>>>
>>My only objection to that is that "dump" suggests you will get some kind
>>of snapshot of current settings, which is not what this facility does.
>>    
>>
>
>I think people will associate dump with pg_dump, meaning "dump out the
>data".  I don't think the snapshot idea will not occur to them.  Copy
>has an in/out capability that doesn't match.
>
>  
>
--display-config might have the more accurate meaning you were looking for.



Re: postgres --help-config

From
Bruce Momjian
Date:
Tom Lane wrote:
> Bruce Momjian <pgman@candle.pha.pa.us> writes:
> > Agreed.  I like --dump-config.  Better to have the verb first.
> 
> My only objection to that is that "dump" suggests you will get some kind
> of snapshot of current settings, which is not what this facility does.
> 
> I don't have an especially good alternative though ... "--describe-config"
> is the only thought that comes to mind right away.

I just realized that --help-config doesn't output the contents of
postgresql.conf at all, but just the internal server defaults.  Does the
admin tool read postgresql.conf too and parse that to get the runtime
values, and how does it know if the postmaster is using the current
postgresql.conf contents or it needs a SIGHUP?

--  Bruce Momjian                        |  http://candle.pha.pa.us pgman@candle.pha.pa.us               |  (610)
359-1001+  If your life is a hard drive,     |  13 Roberts Road +  Christ can be your backup.        |  Newtown Square,
Pennsylvania19073
 


Re: postgres --help-config

From
Tom Lane
Date:
Bruce Momjian <pgman@candle.pha.pa.us> writes:
> I just realized that --help-config doesn't output the contents of
> postgresql.conf at all, but just the internal server defaults.  Does the
> admin tool read postgresql.conf too and parse that to get the runtime
> values, and how does it know if the postmaster is using the current
> postgresql.conf contents or it needs a SIGHUP?

The tool is using the output to help people create postgresql.conf.
The postmaster isn't running.
        regards, tom lane


Re: postgres --help-config

From
Peter Eisentraut
Date:
Tom Lane writes:

> The tool is using the output to help people create postgresql.conf.
> The postmaster isn't running.

But how do you alter postgresql.conf it it already exists but you don't
know the current values?

-- 
Peter Eisentraut   peter_e@gmx.net



Re: postgres --help-config

From
Peter Eisentraut
Date:
Tom Lane writes:

> I don't have an especially good alternative though ... "--describe-config"
> is the only thought that comes to mind right away.

I like that.

-- 
Peter Eisentraut   peter_e@gmx.net



Re: postgres --help-config

From
Peter Eisentraut
Date:
Tom Lane writes:

> > I think there are two ways this can be resolved:
> > 1) Leave it this way, deal with it, but then we can put everything in one
> > field and let the software parse out the first sentence automatically.
>
> True.
>
> > 2) Make real separate "short" and "long" descriptions.
>
> We'd have to break the strings freeze to do that.  How bad do you want it?

I like the first option.  But we'll have to break the string freeze either
way.

-- 
Peter Eisentraut   peter_e@gmx.net



Re: postgres --help-config

From
Tom Lane
Date:
Peter Eisentraut <peter_e@gmx.net> writes:
> Tom Lane writes:
>> The tool is using the output to help people create postgresql.conf.
>> The postmaster isn't running.

> But how do you alter postgresql.conf it it already exists but you don't
> know the current values?

You read postgresql.conf to extract the non-comment lines, and overlay
those on the default values you got from --help-config.
        regards, tom lane


Re: postgres --help-config

From
Tom Lane
Date:
Peter Eisentraut <peter_e@gmx.net> writes:
> Tom Lane writes:
> I think there are two ways this can be resolved:
> 1) Leave it this way, deal with it, but then we can put everything in one
> field and let the software parse out the first sentence automatically.
>> 
>> True.

> I like the first option.  But we'll have to break the string freeze either
> way.

Fernando pointed out to me that the separate-fields approach does help
make it obvious that the first sentence of the description has special
status and needs to be able to stand on its own.  If we merge the
descriptions into one field, it'll be easier to make the kind of mistake
I made with "check_function_bodies".

So I'm back to the opinion that the current setup is not broken, other
than that the fields are misleadingly named, which we could fix easily.
        regards, tom lane