

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

Mon, 29 Sep 2003 08:29:50 +0100
"Dave Page" <dpage@vale-housing.co.uk>
Re: more i18n/l10n issues 
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


Mon, 29 Sep 2003 10:03:09 +0200 (CEST)
Peter Eisentraut <peter_e@gmx.net>
Re: more i18n/l10n issues 
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

>
>  
>



Mon, 29 Sep 2003 11:28:49 +0200
Andreas Pflug <pgadmin@pse-consulting.de>
Re: 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

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

Mon, 29 Sep 2003 10:23:23 -0400
Tom Lane <tgl@sss.pgh.pa.us>
Re: more i18n/l10n issues 

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, Pennsylvania 19073

Mon, 29 Sep 2003 11:57:36 -0400 (EDT)
Bruce Momjian <pgman@candle.pha.pa.us>
Re: more i18n/l10n issues

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, Pennsylvania 19073

Mon, 29 Sep 2003 11:58:41 -0400 (EDT)
Bruce Momjian <pgman@candle.pha.pa.us>
Re: more i18n/l10n issues
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


Mon, 29 Sep 2003 12:17:19 -0400
Andrew Dunstan <andrew@dunslane.net>
Re: more i18n/l10n issues
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

Mon, 29 Sep 2003 12:20:05 -0400
Tom Lane <tgl@sss.pgh.pa.us>
Re: more i18n/l10n issues 
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


Mon, 29 Sep 2003 09:45:14 -0700
Joe Conway <mail@joeconway.com>
Re: more i18n/l10n issues
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, Pennsylvania 19073

Mon, 29 Sep 2003 12:52:04 -0400 (EDT)
Bruce Momjian <pgman@candle.pha.pa.us>
Re: more i18n/l10n issues
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

Mon, 29 Sep 2003 13:56:11 -0400
Tom Lane <tgl@sss.pgh.pa.us>
Re: more i18n/l10n issues 
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


Tue, 30 Sep 2003 11:18:02 +0200 (CEST)
Peter Eisentraut <peter_e@gmx.net>
Re: more i18n/l10n issues
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


Tue, 30 Sep 2003 11:24:50 +0200 (CEST)
Peter Eisentraut <peter_e@gmx.net>
Re: more i18n/l10n issues 
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, Pennsylvania 19073

Tue, 30 Sep 2003 08:25:09 -0400 (EDT)
Bruce Momjian <pgman@candle.pha.pa.us>
Re: more i18n/l10n issues
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

Tue, 30 Sep 2003 09:46:52 -0400
Tom Lane <tgl@sss.pgh.pa.us>
Re: more i18n/l10n issues 
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


Wed, 01 Oct 2003 11:17:00 -0400
Tom Lane <tgl@sss.pgh.pa.us>
Re: more i18n/l10n issues 

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
	   before
	o  uses GNU message reporting style
	o  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, Pennsylvania 19073

Thu, 9 Oct 2003 19:15:41 -0400 (EDT)
Bruce Momjian <pgman@candle.pha.pa.us>
postgres --help-config
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

Thu, 09 Oct 2003 22:07:54 -0400
Tom Lane <tgl@sss.pgh.pa.us>
Re: postgres --help-config 
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, Pennsylvania 19073

Thu, 9 Oct 2003 22:11:34 -0400 (EDT)
Bruce Momjian <pgman@candle.pha.pa.us>
Re: postgres --help-config
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        list available parameter groups\n"));
    printf(gettext("  -h        show this help, then exit\n"));
    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"));

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_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.

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, Pennsylvania 19073

Thu, 9 Oct 2003 22:37:16 -0400 (EDT)
Bruce Momjian <pgman@candle.pha.pa.us>
Re: postgres --help-config
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


Sun, 12 Oct 2003 23:59:37 +0200 (CEST)
Peter Eisentraut <peter_e@gmx.net>
Re: more i18n/l10n issues 
[ 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

Mon, 13 Oct 2003 18:36:40 -0400
Tom Lane <tgl@sss.pgh.pa.us>
Re: postgres --help-config 
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.


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


Tue, 14 Oct 2003 11:34:14 -0400
Fernando Nasser <fnasser@redhat.com>
Re: postgres --help-config
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)

Tue, 14 Oct 2003 15:21:58 -0300
Alvaro Herrera <alvherre@dcc.uchile.cl>
Re: postgres --help-config
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

Tue, 14 Oct 2003 14:53:59 -0400
Tom Lane <tgl@sss.pgh.pa.us>
Re: postgres --help-config 
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.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.

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, Pennsylvania 19073

Tue, 14 Oct 2003 15:05:14 -0400 (EDT)
Bruce Momjian <pgman@candle.pha.pa.us>
Re: postgres --help-config
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

Tue, 14 Oct 2003 19:52:55 +0000 (UTC)
Jon Jensen <jon@endpoint.com>
Re: postgres --help-config
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)

Tue, 14 Oct 2003 16:57:44 -0300
Alvaro Herrera Munoz <alvherre@dcc.uchile.cl>
Re: postgres --help-config
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



Tue, 14 Oct 2003 16:13:01 -0400
Neil Conway <neilc@samurai.com>
Re: postgres --help-config
> > 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.
Tue, 14 Oct 2003 16:32:59 -0400
Rod Taylor <rbt@rbt.ca>
Re: postgres --help-config
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

Tue, 14 Oct 2003 21:04:45 +0000 (UTC)
Jon Jensen <jon@endpoint.com>
Re: postgres --help-config
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


Tue, 14 Oct 2003 23:46:28 +0200 (CEST)
Peter Eisentraut <peter_e@gmx.net>
Re: postgres --help-config
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, Pennsylvania 19073

Tue, 14 Oct 2003 18:08:27 -0400 (EDT)
Bruce Momjian <pgman@candle.pha.pa.us>
Re: postgres --help-config
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

Tue, 14 Oct 2003 18:58:32 -0400
Tom Lane <tgl@sss.pgh.pa.us>
Re: postgres --help-config 
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.
	o There are no docs to show the new flags.
	o You were handling it, and I trusted your style, so I didn't
	  see a 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 agree on 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.
    o Wait 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 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.

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, Pennsylvania 19073

Tue, 14 Oct 2003 20:10:08 -0400 (EDT)
Bruce Momjian <pgman@candle.pha.pa.us>
Re: postgres --help-config
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

Tue, 14 Oct 2003 23:48:48 -0400
Tom Lane <tgl@sss.pgh.pa.us>
Re: postgres --help-config 
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


Wed, 15 Oct 2003 08:09:27 +0200 (CEST)
Peter Eisentraut <peter_e@gmx.net>
Re: postgres --help-config
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.

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

> 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


Wed, 15 Oct 2003 08:20:39 +0200 (CEST)
Peter Eisentraut <peter_e@gmx.net>
Re: postgres --help-config 
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, Pennsylvania 19073

Wed, 15 Oct 2003 09:00:37 -0400 (EDT)
Bruce Momjian <pgman@candle.pha.pa.us>
Re: postgres --help-config
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, Pennsylvania 19073

Wed, 15 Oct 2003 09:06:33 -0400 (EDT)
Bruce Momjian <pgman@candle.pha.pa.us>
Re: postgres --help-config
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, Pennsylvania 19073

Wed, 15 Oct 2003 09:30:18 -0400 (EDT)
Bruce Momjian <pgman@candle.pha.pa.us>
Re: postgres --help-config
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


Wed, 15 Oct 2003 09:33:32 -0400
Andrew Dunstan <andrew@dunslane.net>
Re: postgres --help-config
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

Wed, 15 Oct 2003 10:02:26 -0400
Tom Lane <tgl@sss.pgh.pa.us>
Re: postgres --help-config 
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

Wed, 15 Oct 2003 10:07:17 -0400
Tom Lane <tgl@sss.pgh.pa.us>
Re: postgres --help-config 
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

Wed, 15 Oct 2003 10:49:14 -0400
Tom Lane <tgl@sss.pgh.pa.us>
Re: postgres --help-config 
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


Wed, 15 Oct 2003 10:54:29 -0400
Fernando Nasser <fnasser@redhat.com>
Re: postgres --help-config
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


Wed, 15 Oct 2003 11:22:06 -0400
Fernando Nasser <fnasser@redhat.com>
Re: postgres --help-config
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

Wed, 15 Oct 2003 11:51:26 -0400
Tom Lane <tgl@sss.pgh.pa.us>
Re: postgres --help-config 
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, Pennsylvania 19073

Wed, 15 Oct 2003 15:35:43 -0400 (EDT)
Bruce Momjian <pgman@candle.pha.pa.us>
Re: postgres --help-config
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, Pennsylvania 19073

Wed, 15 Oct 2003 15:36:43 -0400 (EDT)
Bruce Momjian <pgman@candle.pha.pa.us>
Re: postgres --help-config
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, Pennsylvania 19073

Wed, 15 Oct 2003 15:43:30 -0400 (EDT)
Bruce Momjian <pgman@candle.pha.pa.us>
Re: postgres --help-config
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, Pennsylvania 19073

Wed, 15 Oct 2003 16:50:46 -0400 (EDT)
Bruce Momjian <pgman@candle.pha.pa.us>
Re: postgres --help-config
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 switching to
                    temporary disk files
  --...

-- 
Peter Eisentraut   peter_e@gmx.net


Thu, 16 Oct 2003 00:31:59 +0200 (CEST)
Peter Eisentraut <peter_e@gmx.net>
Re: postgres --help-config 
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, Pennsylvania 19073

Wed, 15 Oct 2003 18:41:22 -0400 (EDT)
Bruce Momjian <pgman@candle.pha.pa.us>
Re: postgres --help-config
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

Wed, 15 Oct 2003 19:12:14 -0400
Tom Lane <tgl@sss.pgh.pa.us>
Re: postgres --help-config 
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

Wed, 15 Oct 2003 19:22:56 -0400
Tom Lane <tgl@sss.pgh.pa.us>
Re: postgres --help-config 
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, Pennsylvania 19073

Wed, 15 Oct 2003 21:13:51 -0400 (EDT)
Bruce Momjian <pgman@candle.pha.pa.us>
Re: postgres --help-config
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"

Wed, 15 Oct 2003 23:10:18 -0300
Alvaro Herrera <alvherre@dcc.uchile.cl>
Re: postgres --help-config
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.


Thu, 16 Oct 2003 02:07:02 -0500
Thomas Swan <tswan@idigx.com>
Re: postgres --help-config
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, Pennsylvania 19073

Thu, 16 Oct 2003 13:36:37 -0400 (EDT)
Bruce Momjian <pgman@candle.pha.pa.us>
Re: postgres --help-config
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

Thu, 16 Oct 2003 13:54:58 -0400
Tom Lane <tgl@sss.pgh.pa.us>
Re: postgres --help-config 
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


Fri, 17 Oct 2003 00:30:29 +0200 (CEST)
Peter Eisentraut <peter_e@gmx.net>
Re: postgres --help-config 
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


Fri, 17 Oct 2003 00:31:47 +0200 (CEST)
Peter Eisentraut <peter_e@gmx.net>
Re: postgres --help-config 
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


Fri, 17 Oct 2003 00:34:46 +0200 (CEST)
Peter Eisentraut <peter_e@gmx.net>
Re: postgres --help-config 
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

Thu, 16 Oct 2003 20:00:20 -0400
Tom Lane <tgl@sss.pgh.pa.us>
Re: postgres --help-config 
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

Thu, 16 Oct 2003 20:04:30 -0400
Tom Lane <tgl@sss.pgh.pa.us>
Re: postgres --help-config 